pan-pause git:20261104.d7a9fc8A

Immutable. This exact content never changes and is served at /api/v1/blob/5800a16ad8d2f2a7.

---
name: pan-pause
description: "pan pause <id> [--reason <reason>] — persistently pause an agent and stop it if running"
triggers:
  - pan pause
  - pause agent
  - stop auto resume
  - freeze agent
allowed-tools:
  - Bash
  - Read
---

# pan pause

Run the command now:

```bash
pan pause <issue-id>
```

## Usage

```bash
pan pause PAN-123
pan pause PAN-123 --reason "investigating bad loop"
```

`<id>` also accepts a full agent ID, a conversation name such as `20260928-7563`, `conv/<n>` or `conv:<n>`, and a dashboard URL such as `https://overdeck.localhost/conv/2972`.

## What It Does

`pan pause <id>` sets a persistent pause gate in the agent state file. If the agent is currently running, it also stops the agent so it cannot keep working while paused.

Pausing an issue (its work agent, `agent-<issue>`) holds the issue's review and test work. Its running test agent is stopped, and so is its review convoy when a review is in flight (no verdict yet); reviewers idle after their verdict are left alone. The Deacon's stalled-review recovery leaves the issue alone while it is paused. `pan unpause <id>` re-requests the halted review (a fresh convoy for the current head) or re-dispatches the test agent. If the pause ends any other way (`pan start --force`, dashboard Start with cleared gates), the Deacon re-requests the halted review. Pausing a swarm slot agent pauses only that slot. `pan pause` exits 1 and names any agent it could not stop, including one whose terminal did not close and one whose liveness it could not determine.

Paused agents are skipped by auto-resume. A later `pan start <id>` refuses by default and tells the operator to run `pan unpause <id>` first; `pan start <id> --force` clears the pause gate and starts anyway.

## When to Use

- Use `pan pause` when the agent should stay stopped across Deacon patrols and dashboard restarts.
- Use `pan kill` instead when you only need to stop the current tmux session and still want normal auto-resume behavior.
- Include `--reason` when the next operator needs to know why the gate exists.

## See Also

- `pan unpause <id>` — clear the pause gate without spawning
- `pan start <id>` — start after unpausing, or use `--force` to clear and start
- `pan kill <id>` — stop a session without setting a persistent pause gate