# uip agent escalation

> `uip agent escalation` manages **escalation resources** on an agent project — the human-in-the-loop (HITL) hooks the agent can raise at runtime to request approval, clarification, or review from a human operator. Escalations are persisted alongside tools and contexts as agent resources.

`uip agent escalation` manages **escalation resources** on an agent project — the human-in-the-loop (HITL) hooks the agent can raise at runtime to request approval, clarification, or review from a human operator. Escalations are persisted alongside tools and contexts as agent resources.

Purely local — no login required.

## Synopsis

```
uip agent escalation add    <name> [--description <text>] [--type <type>] [--path <dir>]
uip agent escalation list                                                  [--path <dir>]
uip agent escalation remove <name>                                         [--path <dir>]
```

All subcommands honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## uip agent escalation add

Add an escalation resource.

### Arguments

- `<name>` *(required)* — Escalation name.

### Options

| Flag | Default | Purpose |
|---|---|---|
| `--description <desc>` | — | Human-readable description, stored on the resource. |
| `--type <type>` | `Escalation` | Escalation type. Known values: `Escalation`, `VsEscalation`. Other values may be accepted — run `uip agent escalation add --help` for the current list. |
| `--path <path>` | `.` | Path to the agent project directory. |

### Examples

```bash
# Simplest — default Escalation type
uip agent escalation add ApprovalRequired --path ./my-agent

# With description
uip agent escalation add ApprovalRequired \
  --description "Require human approval before executing refund" \
  --path ./my-agent

# VsEscalation (Studio Desktop action-center flavour)
uip agent escalation add Review --type VsEscalation --path ./my-agent
```

### Data shape (--output json)

```json
{
  "Code": "AgentEscalationAdd",
  "Data": {
    "Status": "Escalation added",
    "Name": "ApprovalRequired",
    "Type": "Escalation",
    "Id": "a1b2c3d4-0000-0000-0000-000000000020"
  }
}
```

`Id` is a generated UUID. Use either `Name` or `Id` with `escalation remove`.

## uip agent escalation list

Enumerate the escalation resources configured on the agent.

### Options

| Flag | Default | Purpose |
|---|---|---|
| `--path <path>` | `.` | Path to the agent project directory. |

### Example

```bash
uip agent escalation list --path ./my-agent
```

### Data shape (--output json)

```json
{
  "Code": "AgentEscalationList",
  "Data": [
    {
      "Name": "ApprovalRequired",
      "Type": "Escalation",
      "Id": "a1b2c3d4-0000-0000-0000-000000000020"
    }
  ]
}
```

Empty projects return `Data: { "Message": "No escalations configured" }`.

## uip agent escalation remove

Remove an escalation resource.

### Arguments

- `<name>` *(required)* — Escalation name **or** ID.

### Options

| Flag | Default | Purpose |
|---|---|---|
| `--path <path>` | `.` | Path to the agent project directory. |

### Example

```bash
uip agent escalation remove ApprovalRequired --path ./my-agent
```

### Data shape (--output json)

```json
{
  "Code": "AgentEscalationRemove",
  "Data": {
    "Status": "Escalation removed",
    "Name": "ApprovalRequired"
  }
}
```

A missing escalation fails with `Escalation "<name>" not found` and exit code `1`.

## Related

- [`uip agent tool`](./uip-agent-tool-manage.md) — add tool resources the agent can invoke alongside escalations.
- [`uip agent context`](./uip-agent-context-manage.md) — RAG context resources.
- [`uip agent validate`](./uip-agent-validate.md) — verifies resource integrity after edits.

## See also

- [Concepts: skills](./concepts-skills.md) — how escalations fit into the broader skill model.
- [Global options](./global-options.md), [Exit codes](./exit-codes.md).