For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

An approval is the point where an agent stops and asks a person whether it may proceed. Harness Runtime raises one whenever an action the agent wants to take resolves to ask under the session’s permission policy. The run holds until the request is resolved, so approvals are the control that keeps a long-running agent from taking a consequential step unsupervised.

What Triggers an Approval

The agent requests approval for the category of action, not for a specific decision it has already made. The common categories are:

• Running a shell command.
• Writing to a file outside the workspace.
• A write operation against a connected provider, such as pushing to a repository.
• Calling an MCP tool.

An action is only gated if the policy says so. With default: allow and no ask rules, a session never raises an approval, and the agent runs to completion without stopping.

What an Approval Request Contains

Each request carries an ID, the session and run it belongs to, the category of action, the working directory the agent is in, and the details of the action itself, such as the exact command it intends to run. Read the details rather than the category. The category tells you the agent wants to run a shell command; the details tell you it wants to run rm -rf.

A request can carry a deadline. When one expires without an answer, the agent is told the request was not approved.

Responding to an Approval

Defer is not a delayed approval. Nothing retries a deferred request on your behalf, and the agent decides whether to ask again.

When you are attached to a session, a pending request prompts in the terminal and a single key answers it: y or a to approve, n or r to reject, and d to defer. No Enter is needed. The slash commands /a, /r, and /d do the same thing, and /pending lists everything waiting.

You can also answer without being attached, which is how you unblock a session you left running:

doctl harness-runtime approve <your-session-name> <request-id> approve

The final argument accepts approve, reject, or defer.

The Pending Queue

Requests queue in the order they were raised, and an answer given without naming a request ID resolves the oldest one. Name the request ID explicitly when several are pending, so that an answer intended for one action is not applied to another.

Ending a run cancels any approvals still pending on it. They are not carried into the next run.

Unattended Runs

An agent waiting on an approval that nobody answers is a stalled session. For runs that start without a person watching, decide the policy up front rather than at the prompt.

Sessions started by a trigger resolve approvals automatically. Because of this, a trigger that creates a fresh session for each firing rejects a spec whose policy uses ask, either as the default or in a rule. Express the intent in the policy with allow and deny instead.

For a headless run you start yourself, doctl harness-runtime create --on-hitl watches the session and applies one response to every approval it sees. Combine it with --interactive=false for automation that must never block on a prompt.

Approvals and Action Gateway

Approvals in this page are raised by the agent inside the sandbox. Action Gateway tools are governed separately and do not use this flow: a gateway rule set to ask refuses the call with a message rather than prompting you. See Where rules are enforced.