Safety, limits and feedback

Approvals

Review, approve or deny the risky actions that agents and unattended runs ask for, and choose when Orkestra asks.

On this page

Purpose

An agent can ask Orkestra to do something that does harm, for example to run a command that deletes files. Orkestra can hold such a request and ask you first. This chapter explains the approval dialog, the Approvals list in the status bar, and the Approvals settings that decide when Orkestra asks.

Four agent actions can raise a request: send text to a terminal, launch a task, open an agent terminal, and launch a group of tasks. The caller can be an agent in an Orkestra terminal, an outside tool, the Helm assistant, Telegram remote control or an unattended run. A built-in rule set checks the text. Most requests pass with no question. Only a flagged request waits for you.

Where to find it

  • Approvals item in the status bar, right group, between the project operations item and Agents. It is always shown. Its accessible name is "Open approvals". Click it to open the Approvals list.
  • Approvals in the Settings window. Open Settings (gear icon in the top bar), then click Approvals in the left list. The Approval rules… button in the Approvals list opens the same pane.
  • Orkestra never opens the list or the dialog by itself. It plays no sound and shows no system notice for a request. The count on the status bar item is the only signal in the window. Telegram can also show the request. See Remote control with Telegram.

What you see

Status bar item

  • An icon. A number appears next to it while requests wait. The item is amber while requests wait. It is faint, with no number, when none wait.

Approvals list (a panel that opens upward from the item)

  • Approvals title with a count badge. A blue N new chip shows when requests exist that you have not opened.
  • ✕ button (tooltip "close Approvals").
  • A red banner with Retry when Orkestra cannot read the list. A red banner with the error when an answer fails.
  • One row for each waiting request.
  • For a few seconds after a request ends: a settled row (see "States and messages").
  • A foot with the note "Opening a request never approves it." and the Approval rules… button.

Request row

  • A tile: a shield for one request, a stack of layers for a group.
  • Title: "<who> → <destination>". A small blue dot and a stronger title mark a request you have not opened.
  • Detail line: "<tool> · <project>". For a group: "group.launch · 1 of 3 members approved".
  • Countdown in minutes and seconds.
  • Deny and Approve for one request. Review for a group.

Approval dialog (one request). Title Approval required, a shield tile, a status chip (WAITING) and a ✕ button (tooltip "cancel"). Body, top to bottom:

  • From — who asks: a name such as "Helm", "External MCP client" or "Terminal <id>"; the connection (for example "external MCP connection"); and a short key fingerprint that starts with "sha256:". The tag CLAIMED NAME — UNVERIFIED shows a name the caller gave itself. The text reads "no name supplied with this request" when it gave none. Orkestra does not check a name that the caller supplies.
  • Destination — the target and the project, for example "api-server · My project".
  • Tool — the name of the action.
  • Requested — the time of day of the request.
  • Reviewed input with the note "secrets redacted before display" — the exact text the agent wants to send. A small chip names each secret that Orkestra hid.
  • Submitted task — shown instead of Reviewed input when approving would create a new task. It has the tag PREVIEW — NOT CREATED, the title, the description and, when known, the agent, the branch and "launches 1 terminal". A long description shows four lines and the note "Clamped for review — the full text is what gets created." A blue banner says nothing is created or run until you approve. A Startup command block shows a command that the new terminal will run.
  • Rule line — the name of the rule that flagged the request and one sentence about it.
  • Approve for this session and Always approve — only when the request allows them.
  • Inspect row — a link to the terminal or the task (see below).
  • A countdown bar: "m:ss left" and "then denied".
  • Foot: a note, Deny and Approve once.

Group dialog (a launch of a task group). Title "Group launch — Release checklist". Chip WAITING, or HELD · 1/3 after some members are approved.

  • From block, as above.
  • A blue banner: "Nothing has started. The group launches only when every member is approved — approvals so far are held, not executed."
  • Members list with the project. Each row has a state icon, the task title in bold, and the agent and worktree. A member that waits has Deny and Approve buttons. Any other member has a chip: APPROVED, DENIED, DISCARDED or NOT ASKED.
  • Inspect row: "Nothing to reveal yet — no member has launched."
  • A countdown bar: "m:ss left" and "then remaining members are denied".
  • Foot: Deny remaining and Approve remaining.

Settings → Approvals has three groups.

  • Approval policy: the Enable approval checks switch and Upstream mode buttons Manual, Smart and Off. This mode sets the default review policy while checks are enabled; turning checks off skips all approval rules.
  • Audiences: the check boxes Review external agents, Review internal agents and Exempt headless callers.
  • Permanent grants: one row for each saved Always approve rule, each with a Remove button. The row text is "<source> -> <tool> · <project>". A small line under it names the rule.

How to

Open the Approvals list

  1. Click the Approvals item in the status bar.

Result: the Approvals list opens above the bar. Orkestra reads the waiting requests again each time you open it. Click the item again to close it.

Answer a request from the list

  1. Click the Approvals item in the status bar.
  2. Find the row of the request.
  3. Click Approve to allow it once, or click Deny to refuse it.

Result: the row turns into a settled row, for example "Denied — nothing ran", and leaves after four seconds. Nothing is kept as history.

Review a request in the dialog and approve it once

  1. Click the Approvals item in the status bar.
  2. Click the row of the request.
  3. Read From, Destination, Reviewed input (or Submitted task) and the Rule line.
  4. Click Approve once.

Result: Orkestra checks that the target is the same as when the request began. If it is, Orkestra does the action, the dialog closes, and the list shows "Approved — written to <destination>".

Deny a request in the dialog

  1. Click the Approvals item in the status bar.
  2. Click the row of the request.
  3. Click Deny.

Result: the dialog closes and the list shows "Denied — nothing ran". The agent receives a refusal.

Look at the terminal or the task behind a request

  1. Click the Approvals item in the status bar.
  2. Click the row of the request.
  3. In the Inspect row, click Reveal <terminal name> to see the terminal that gets the text. Click Open task details to see an existing task. Click Sender: <id> to see the terminal that sent the request.
  4. Click the ✕ button (tooltip "cancel") to close the dialog.

Result: Orkestra switches to the project and workbench of the terminal, brings its window to the front and flashes it. The view does not pan. For a task, Orkestra opens the task window in focus mode. The dialog stays open until you close it, and the request stays waiting. Looking never approves.

Approve a request for this session or always

Before you start, open the dialog of a request that shows these buttons. Many requests show only Approve once.

  1. Click Approve for this session to allow the same kind of request from the same source until Orkestra closes.
  2. Or click Always approve to save a rule that stays after a restart.

Result: Orkestra approves this request and does not ask again for the same source, tool, project and rule. A saved rule appears in Permanent grants in Settings.

Answer a group launch

  1. Click the Approvals item in the status bar.
  2. Click Review on the group row.
  3. Click Approve on a member row to approve that member only. Or click Approve remaining in the foot to approve all members that wait.

Result: an approved member shows APPROVED and the chip in the title shows HELD · n/m. The whole group starts only when the last member is approved. If you click Deny on a member, or Deny remaining, the whole group is cancelled and no member starts. Approved members then show DISCARDED.

Answer a request from Telegram

Before you start, turn on remote control and pair Telegram. See Remote control with Telegram.

  1. Open your Orkestra bot chat in Telegram.
  2. Read the message that starts with "Approval needed".
  3. Tap Approve once or tap Deny.

Result: the message changes to the outcome, for example "Approved — sent to "<terminal>"." or "Denied — nothing ran." The desktop request settles in the same way.

Change the review mode

  1. Click the gear icon (tooltip "Settings") in the top bar.
  2. Click Approvals in the left list.
  3. Under Upstream mode, click Manual, Smart or Off.
  4. Click Apply or OK.

Result: the new mode applies to the next request. See "Limits and tips" for what each mode does.

Choose which agents Orkestra reviews

  1. Open Settings and click Approvals.
  2. Under Audiences, click Review external agents to review tools outside Orkestra.
  3. Click Review internal agents to review the agents in your Orkestra terminals.
  4. Click Exempt headless callers to skip, or to review, unattended runs.
  5. Click Apply or OK.

Result: Orkestra reviews the groups that you chose from the next request on.

Turn approval checks off

  1. Open Settings and click Approvals.
  2. Click Enable approval checks to clear the check box.
  3. Click Apply or OK.

Result: Orkestra stops all checks, including the checks that always refuse the worst commands. The other controls stay editable but have no effect.

Remove a permanent grant

  1. Open Settings and click Approvals.
  2. In Permanent grants, find the rule.
  3. Click Remove on its row.

Result: the row disappears at once. The next matching request asks you again. Cancel does not bring the rule back.

States and messages

  • Status bar item. Amber with a number: requests wait. Faint with no number: none wait.
  • Empty list. "Nothing waiting for approval. Requests from connected agents appear here."
  • List error. "Approval requests could not be loaded. Retry to check again." Click Retry.
  • Answer error. A red message in the list or in the dialog foot, for example "Approval request is no longer pending." (the request ended or was answered elsewhere), "Invalid approval answer." or "Approval answer failed." It goes away when you close the list.
  • Dialog foot note. "Viewing never approves — <name> stays blocked until you decide." For a group: "Members launch together once the last one is approved."
  • Chips. WAITING is amber. HELD · n/m is blue. APPROVED is green. DENIED is red. DISCARDED and NOT ASKED are grey.
  • Countdown. A request waits about 5 minutes from the moment it starts. The bar is full at 5:00. The time line turns red under 30 seconds.
  • Inspect row, no target. "Nothing to reveal yet — the task doesn't exist." (a task that approval would create), "Nothing to reveal yet — the terminal hasn't opened." (a terminal that approval would open) or "Nothing to reveal yet — no member has launched." (a group).
  • Settled rows, in the list for four seconds, with the note "row leaves in 4 s · decisions aren't kept":
    • "Approved — written to <destination>".
    • "Denied — nothing ran". This also shows when you approve but the target changed in the meantime, for example the terminal was replaced or the task text was edited.
    • "Expired unanswered — treated as denied". Nobody answered in time.
    • "Approved — action failed". You approved, but Orkestra could not do the action.
    • "Request cancelled before approval". The agent stopped waiting, its terminal closed, or Orkestra shut down.
  • Settled group. A strip with "This card closes by itself. Decisions aren't kept — there is no approval history." After a refusal it names the member: "<title> was denied — the group launch is cancelled. Held approvals were discarded; no member started." It then lists every member with its chip.
  • Override card. In Smart mode the automatic review can refuse a request. The card then reads "Override available for m:ss" and "then this card closes". You can still allow that one request. Only Approve once is offered.
  • Permanent grants. "No permanent approval grants." while the list is empty. Remove changes to "Removing…" while Orkestra works. Errors show as plain text above the list, for example "Permanent grants could not be loaded." or "Permanent approval grant could not be removed."

Limits and tips

  • Which actions are reviewed. Only the four actions listed in Purpose, and only when an agent or other client asks for them. Things you do yourself in the Orkestra window are never reviewed. Other agent actions, such as pressing keys in a terminal or opening a plain terminal, are not reviewed.
  • Defaults. Checks are on. The mode is Smart. Review external agents is on. Review internal agents is off, so agents in your Orkestra terminals are not reviewed until you turn it on. Exempt headless callers is on. The Helm assistant and Telegram remote control have no switch: Orkestra always reviews them while Enable approval checks is on.
  • Manual. Orkestra shows every flagged request to you at once.
  • Smart. An automatic review reads a flagged request first. It runs on the routine engine in Settings → Helm → Routine model. See Settings: Helm. It can approve alone, so you see no dialog. If it refuses or is unsure, or if it fails, the dialog or the override card appears. The review takes up to 30 seconds, so the dialog can come late. The 5 minutes count from the start of the request.
  • Off. Orkestra skips the normal review. It still refuses the worst commands. Enable approval checks off skips even those.
  • Always refused. Some commands are refused at once, with no dialog and no way to override. The agent only sees the refusal.
  • Grants. Approve for this session ends when Orkestra shuts down. It is not listed in Settings. Always approve is saved and listed in Permanent grants. A grant fits one source, one tool, one project and one rule, so a new terminal needs a new approval. Requests flagged for their wording, requests to open an agent terminal, and group launches allow only Approve once.
  • Agents cannot change these settings. An agent that edits Orkestra settings through the MCP server cannot change Approvals.
  • No history. Orkestra does not keep decisions. Waiting requests do not survive a restart. Quitting Orkestra cancels them.
  • Many requests. Orkestra holds at most 32 waiting requests. More requests are refused at once.
  • Two places, one answer. You can answer in the app or in Telegram. The first answer wins. A late tap shows "This request is no longer pending." Telegram offers only Deny and Approve once, and only while remote control is on, a chat is paired and Pause inbound messages is off.
  • Other questions. The permission questions that the Helm assistant asks in its own chat are a different feature. See Helm assistant. A coding agent can also stop and wait for you in its own terminal. That is the Awaiting input status, not an approval request. Codex shows Awaiting input only when Codex itself asks you. A command that Codex reviews automatically does not show it. See Agents panel and agent status.