All pages

Docs · AI features

Agent safety

Availability: macOS.

The agent's defense-in-depth lives in the Safety panel (shield icon, top-right of the agent sidebar). Every tool call is classified, every gated action is logged, and every approval can be scoped down or rolled back. ⌘. stops the running turn. ⇧⌘. is the panic shortcut: it stops the current turn, revokes pending approvals, and locks the agent down until you resume.

Posture chip

The chip in the agent sidebar header shows the current session's posture and cycles with ⇧Tab (or click).

Posture What it does
Approve (gray) Default. WRITE tools surface an approval card; READ tools run silently.
Auto-accept (green) Every tool runs without confirmation. Use for known-safe workflows.
Observe (blue) Read-only enforcement. Writes and shell commands are blocked at the runner.

Posture is per-project and survives session restart. The destructive-verb gate and per-tool always-prompt carve-out still fire even on Auto-accept.

READ vs WRITE tags

Every tool is tagged READ (blue badge) or WRITE (orange badge) in the Safety panel's Tools tab. WRITE tools require approval by default. Classification comes from AgentToolName.requiresApproval for built-in tools and from each external provider's requiresApproval() for plugin and MCP tools.

Always-prompt carve-out

Toggle Always prompt on any individual tool to force an approval card even when the session is on Auto-accept. Useful for singling out one risky tool (browser_navigate, bash) without abandoning auto-approve everywhere else. Saved per project; does not override hard denies.

Approval rules

When you approve a tool call, the approval card menu offers:

  • Approve / Deny (this call only)
  • Allow this tool / Deny this tool — a standing rule for this tool in this project
  • Allow this path / Allow this directory — scoped to the file or folder this call touches
  • Allow on <host> / Deny on <host> — scoped to the URL host of this call

Rules are persisted per project. Specificity wins: a host-scoped rule beats a tool-only rule for the same call.

Allow this directory scopes to a real folder, and the match stops at a path component — a rule on proj never covers proj-secrets.

A standing "Allow…" rule, and the branch guard, judge a call by the folder it will actually run in: the sidebar's own window, the pinned worktree, or the project a project:-scoped call names. Not whichever tab happens to be in front.

Working an approval card by keyboard

⌃J and ⌃K move focus between the turn's tool cards and scroll the focused one into view. ⌘↩ approves the focused card; ⌘⌫ denies it.

Edit args opens the call's input for editing before you decide. Approve commits an open draft first, so the card runs what it shows rather than what the model originally sent. Reveal shows a file tool's target in Finder — it selects the file rather than opening it, so revealing a .command or a script can't run it.

Multi-file review gate

When a single turn writes to more than one path with write_file, edit_file, or apply_patch, each of those cards shows its diff inline and Approve stays disabled until every sibling has been marked Reviewed diff. The point is that you see the whole change before any part of it lands. A turn touching one file is gated only by its own approval card, as usual.

Persona and sub-agent limits

A persona's narrowed tool allowlist is enforced when the tool runs, not only when the model is handed its tool list — a call for something outside the list is refused rather than quietly allowed. spawn_subagent cannot give a sub-agent a tool its parent chat doesn't have.

Network egress allowlist

web_fetch and browser navigation are gated by an app-wide egress allowlist (Safety panel → Network, or Settings → Security). Modes:

  • Open — any non-private host allowed
  • Allowlist — only listed host suffixes allowed (the default on new installs, seeded with a few safe hosts like github.com and apple.com)

Localhost dev servers bypass the check for browser navigation; web_fetch always refuses loopback and private addresses.

The agent has tools to read and extend the allowlist:

Tool Approval Use
browser_allowlist_list no Snapshot mode + hosts
browser_allowlist_add yes Add a host suffix to the allowlist
browser_request_allowlist yes Alias of add framed as an explicit user request — used as a recovery path after egress denial

When a navigation is denied, the denial banner links straight to browser_request_allowlist and the Safety panel so the agent can ask for one specific exception rather than turning off allowlisting.

Audit log

Safety panel → Audit Log is an append-only NDJSON record of every tool call, approval, denial, and rule change:

~/Library/Application Support/TRMNLY/agent-audit.ndjson

Each entry is signed into an HMAC chain — the Verify integrity button on the Session tab recomputes every signature against the Keychain-stored key. The in-memory buffer holds 500 entries; full history persists to disk.

audit_list lets the agent read what remote devices (the paired phone, a paired browser) did on this Mac, newest first, refused calls included. Filter by since, device (a token-hash prefix) or tool; remote_only: false adds local MCP clients.

  • Per-row Revoke. Any .toolCall or .approvalGranted row has a one-click Revoke that locks the tool for the project and clears any saved approval rules tied to it. Useful for "I just realized I approved too much."
  • Recent-activity badge. The Safety panel's icon shows a numeric badge counting tool calls in the last 5 minutes — a glanceable signal that the agent has been doing things.

Destructive verb gate

A short list of irrecoverable shell verbs fire a one-shot prompt the first time each appears in a session, even on Auto-accept:

  • rm -rf / any recursive or forced delete
  • rm targeting /
  • git push --force / --force-with-lease
  • git clean -fd / -fx
  • git reset --hard
  • DROP DATABASE / DROP SCHEMA / DROP TABLE
  • TRUNCATE TABLE
  • dd of=/…
  • mkfs.*
  • shutdown / reboot / halt / poweroff
  • kill -9 -1 / pkill -9
  • chmod -R … /

Approve once and that exact verb drops back to normal policy for the rest of the session. Re-arm individual verbs (or all of them) from the Session tab to reset the gate. The Session tab also has a Session read-only toggle — it blocks every approval-gated tool for just this chat and resets when you switch.

Branch guard

Two-key confirmation for irreversible commands while the working directory is on a protected branch — main, master, prod, production, release, or anything starting with release/. Gated commands include force pushes, plain git push origin to the protected branch, git reset --hard, git clean -f, recursive deletes, and DROP/TRUNCATE. The approval card demands two confirm clicks within 8 seconds — miss the window and both clicks reset. A denied attempt issues a fresh ticket, so a retry re-confirms from scratch.

Settings → Permissions vs Security

Two distinct panes:

  • Permissions — OS-level privacy grants TRMNLY needs (Accessibility, Automation, Microphone, Notifications, Screen Recording, Full Disk Access). Status pills, in-app request where supported, deep-link out to System Settings otherwise.

    Grants are keyed to the developer team rather than to one signing certificate, so a released build, an updated build, and a copy you built yourself all satisfy the same grant — a permission given once keeps working. Screen Recording is the exception to "it takes effect immediately": macOS applies it only to a freshly launched process, so relaunch TRMNLY after allowing it. Grant Accessibility before leaving a long run unattended — without it the agent lock's stuck-state rescue can notice clicks but not keystrokes.

  • Security — scripting consent for external sources, the agent network egress mode + allowlist, the audit log's location, diagnostics logging, plugin permission grants, and the update channel.