> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Approval System

> Human-in-the-loop controls for agent actions

## Overview

The approval system lets each squad declare what agents can do automatically
vs. what requires human sign-off. That declaration lives in plain YAML in
`SQUAD.md` — it's read by critic agents doing PR review, and (if you run a
companion API + Slack app) by an interactive approve/reject flow. The two are
independent: the policy is useful as documentation and as a critic-agent gate
even if you never wire up Slack.

<Note>
  This is a different mechanism from [governance](https://github.com/agents-squads/squads-cli/blob/main/docs/governance.md), which protects `goals.md`/`directives.md`/`SQUAD.md` themselves from autonomous edits via native Claude Code permission rules. Approvals gate what an agent *does*; governance gates what an agent can *rewrite*.
</Note>

**Four levels of autonomy:**

| Level     | Actions                     | Human Involvement                                |
| --------- | --------------------------- | ------------------------------------------------ |
| `auto`    | Safe, reversible operations | None — agent proceeds                            |
| `notify`  | Worth knowing about         | Posted, agent proceeds without waiting           |
| `approve` | Significant but routine     | Async approval (Slack)                           |
| `confirm` | High-impact decisions       | Sync confirmation, escalates to a higher channel |

***

## Configuration

Each squad's `SQUAD.md` contains an `approvals:` section:

```yaml theme={null}
approvals:
  channel: "#squad-engineering"
  notify: ["@jorge"]         # who gets @-mentioned, independent of the tiers below

  policy:
    auto:
      - memory.update
      - goal.set
      - branch.create
      - issue.create
      - pr.create
      - agent.run.readonly

    notify:
      - release.draft

    approve:
      - pr.merge
      - trigger.fire
      - agent.run.write

    confirm:
      - deploy.production
      - schema.migrate
      - secret.rotate

  thresholds:
    spend_approval: 15.00
    bulk_actions: 5
    files_changed: 20
```

***

## Action Categories

### Auto Actions

Agents execute immediately without human intervention:

| Action               | Description               |
| -------------------- | ------------------------- |
| `memory.update`      | Update squad memory files |
| `goal.set`           | Set or update squad goals |
| `branch.create`      | Create feature branches   |
| `issue.create`       | Open GitHub issues        |
| `issue.comment`      | Comment on issues         |
| `pr.create`          | Create pull requests      |
| `commit.push`        | Push commits to branches  |
| `build.run`          | Run build commands        |
| `test.run`           | Run test suites           |
| `agent.run.readonly` | Execute read-only agents  |

### Notify Actions

Posted to the channel, but the agent proceeds without waiting:

| Action          | Description           |
| --------------- | --------------------- |
| `release.draft` | Create release drafts |

### Approve Actions

Require async approval via Slack:

| Action            | Description                  |
| ----------------- | ---------------------------- |
| `pr.merge`        | Merge pull requests          |
| `release.publish` | Publish releases             |
| `trigger.fire`    | Manually fire triggers       |
| `infra.change`    | Infrastructure modifications |
| `agent.run.write` | Execute write-capable agents |

### Confirm Actions

Require synchronous confirmation before proceeding:

| Action              | Description               |
| ------------------- | ------------------------- |
| `deploy.production` | Production deployments    |
| `schema.migrate`    | Database migrations       |
| `secret.rotate`     | Rotate secrets            |
| `mission.change`    | Mission statement changes |
| `org.restructure`   | Organizational changes    |
| `budget.exceed`     | Over-budget decisions     |

***

## Thresholds

Automatic escalation based on impact:

```yaml theme={null}
thresholds:
  spend_approval: 15.00    # USD - actions exceeding this need approval
  bulk_actions: 5          # Operations affecting >N items
  files_changed: 20        # PRs touching >N files
```

### How Thresholds Work

1. **Spend Threshold**: Agent tracks cumulative spend. When approaching threshold, pauses for approval.

2. **Bulk Actions**: Creating >5 issues? Closing >5 PRs? Requires approval.

3. **Files Changed**: Large PRs automatically require squad lead review.

***

## Approval Flow

<Note>
  Interactive Slack approve/reject buttons require a running companion API
  (`SQUADS_API_URL`) with a Slack app configured — that's part of the hosted
  platform, not something the standalone local CLI spins up for you. Without
  it, `squads approval send` records a request but nothing decides it. What
  works standalone: `squads add` auto-creates a `#squad-<name>` Slack channel
  if `SLACK_BOT_TOKEN` is set, and critic agents can enforce the same `policy:`
  tiers directly on a PR without any Slack integration at all.
</Note>

### CLI Approval

```bash theme={null}
# Send an approval request — type is one of: issue, pr, content, run, brief
squads approval send pr --title "Merge feature X" --json '{"repo":"my-org/my-repo","number":123}'

# List pending approvals
squads approval list

# Check status (add --wait to poll until decided)
squads approval check appr_abc123 --wait
```

`squads approval cancel <id>` exists in the CLI but isn't implemented yet
server-side — sending it is currently a no-op.

***

## Escalation

Some actions escalate to higher-level channels:

```yaml theme={null}
confirm:
  - deploy.production    # Escalate to #company
  - schema.migrate       # Escalate to #company
```

When an action is in `confirm`, it escalates from the squad channel to the company channel, requiring explicit confirmation before proceeding.

***

## Timeout Behavior

Approvals have configurable timeouts:

| Type      | Default Timeout | On Timeout             |
| --------- | --------------- | ---------------------- |
| `approve` | 4 hours         | Reminder, then abandon |
| `confirm` | 1 hour          | Abandon, create issue  |

***

## Per-Squad Examples

### Engineering Squad

```yaml theme={null}
approvals:
  channel: "#engineering"
  notify: []  # GitHub watched directly

  policy:
    auto:
      - issue.create
      - pr.create
      - commit.push
      - release.draft
    approve:
      - pr.merge
      - release.publish
    confirm:
      - deploy.production  # → #company
```

### Company Squad

```yaml theme={null}
approvals:
  channel: "#company"
  notify: ["@jorge"]

  policy:
    auto:
      - memory.update
      - goal.set
    approve:
      - sprint.approve
      - strategy.update
    confirm:
      - mission.change
      - org.restructure
```

***

## Best Practices

### 1. Start Restrictive

Begin with most actions in `approve`, move to `auto` as trust builds.

### 2. Use Thresholds

Don't make everything require approval. Use thresholds to catch outliers.

### 3. Clear Channels

Each squad should have a dedicated approval channel. Don't mix with general chat.

### 4. Timely Responses

Blocked agents waste compute. Respond to approvals quickly or adjust policies.

### 5. Document Exceptions

If you approve something unusual, note why in the approval response.

***

## Monitoring Approvals

```bash theme={null}
# Autonomy score and confidence metrics, including response times
squads autonomy --period week
```

Slow approval times indicate policies may be too restrictive.