Approve every write.

Reads happen. Writes wait. Connections default to read-only.

Read vs. write

Every tool call is classified before it runs. Reads execute and stream their result. Writes pause and surface an approval card with the full payload — the actual SQL, the actual file edit, the actual cell change — and two buttons: Approve or Reject.

The classification is conservative:

  • Read — SELECT, SHOW, EXPLAIN, file reads, schema inspection, safe shell commands (ls, cat, grep, git status, etc.).
  • Write — INSERT, UPDATE, DELETE, DROP, TRUNCATE, CREATE, ALTER, file overwrites, cell replacements, new file creation, package installs, mutating shell commands.

Anything ambiguous — like a stored procedure call with unknown side effects — is treated as a write.

An approval card for an UPDATE statement with the full SQL displayed and approve / reject buttons./docs-images/agents/approval-card.png
Every write surfaces with the full payload before it runs.

Connection-level locks

Connections default to read-only. SQL writes are refused at the runner level — even if the agent (or you) tries to slip one through, the call fails before it reaches the database.

To allow writes on a connection, open Integrations → [connection] → Permissions and lift the lock. Orchid asks for a confirmation step and shows a lock icon on every cell that uses the connection from then on. You can revoke write access at any time.

Status icons on a SQL cell header:

  read-only    SELECT/SHOW only; writes refused
  write        lock lifted on this connection; writes require approval
Warning

Lifting a write lock affects both you and the agents. Even with the lock lifted, individual write statements still need explicit per-call approval — but the channel is open. Lock it back down when you're done.

Proposed cell changes

Cell-level proposals — new cells, replacements to existing ones, insertions — render inline in the notebook with a soft outline and a Review banner. Three options:

  • Accept — the proposal becomes a real cell, saved to the file.
  • Reject — the proposal disappears; no diff is recorded.
  • Edit — open the diff, tweak the content, then accept your version.

Until you accept, the proposed cell is virtual — not in the YAML, not visible to dashboards that pin cells from this notebook, and not saved on disk.

The action log

Open the Activity tab in the agent panel for the full audit trail. Every entry has:

  • Timestamp — when the call ran or was approved.
  • Tool name — query, execute_code, etc.
  • Inputs and outputs — the full payload, expandable.
  • Token cost — for the chat turn that triggered the call.
  • Status — succeeded, failed, rejected, pending.
  • Speaker — which specialist ran it, in multi-agent mode.
The activity log with a list of tool calls, status badges, and timestamps./docs-images/agents/activity-log.png
The activity log doubles as an audit trail.

What the agent literally cannot do

  • Touch files outside the current project workspace.
  • Write to a read-only connection.
  • Approve its own writes — only you can.
  • Run a mutating shell command without your approval — the run_command tool refuses unknown binaries by default.
  • Modify connection credentials, billing, or other agents' settings.
Note

The safety model applies the same way to single and multi-agent modes. Specialists in multi-agent mode don't inherit special privileges — every write still needs your click.

Back to Agents overview, or read about the tool registry and prompting tips.