How Agent Approve works

Agent Approve connects to the hook, plugin, or extension system provided by your coding agent. You keep working in the agent as usual.

From an action to a decision

1. A supported integration sees a command or tool call before it runs.
2. Your computer sends the request to Agent Approve over an encrypted connection. When end-to-end encryption is enabled, Approval Mode creates separate encrypted copies: one the service can open for policy evaluation and one only your devices can open for live review and event history.
3. Agent Approve evaluates the request against your active policy.
4. A Deny List match is denied. An Allow List match is approved. A request that still needs a decision is sent to your iPhone and, if connected, Apple Watch.
5. You review the request and choose Approve or Deny. You can also remember the decision as a policy rule.
6. The result returns to the integration so the agent can continue or stop.

The exact events and controls available depend on the integration. See Integration capabilities before relying on a feature with a particular agent.

Compound shell commands

For supported shell tools, Agent Approve checks both the complete command and the individual commands in a shell sequence. This helps catch a denied operation that appears after a pipe, conditional operator, or command separator.

An allowed command at the beginning of a sequence does not make a denied command later in the sequence safe.

For example, each of these requests is evaluated as more than one command:

git status && git diff

echo ready; make test; echo done

cat build.log | grep error && echo found

The command at the beginning does not hide a later command from policy. Separators inside quoted text remain part of that text instead of being treated as a new command.

• If any parsed command matches the Deny List, the whole request is denied.
• Every parsed command must match the Allow List before the whole request can be approved automatically.
• If the policy cannot decide every part, Agent Approve sends the request to you for review.

Shell parsing is an added safeguard, not a substitute for reviewing the full request. Scripts, variables, and programs can change behavior at runtime.

Approval Mode and Observe Mode

In Approval Mode, supported actions can wait for policy or for your decision before they run. In Observe Mode, Agent Approve records supported activity but does not pause the agent for approval.

Read Approval Mode and Observe Mode before choosing which mode to use for unattended work.

What appears in history

Agent Approve groups reported activity by agent instance. Depending on the integration, that can include commands, tool calls, responses, completion events, subagent activity, and profile names.

Your selected Privacy Level controls how much content is kept in history. Data Retention controls how long that history remains available in your app.

The full approval copy used for centralized policy and live review is separate from the privacy-filtered history copy. Read Privacy and encryption for what the service processes, retains, and encrypts for your devices.