---
name: annotate
description: Read a cueloop plan or diff and comment on it as a review-side agent, without leaving the review. Use when you are helping a collaborator poke holes in a plan under review - you annotate on their behalf; you never rewrite the plan or cast the message.
---

# cueloop annotate

The agent side of the review write-surface. You read the artifact under review
and attach span-anchored comments through the same annotation API a human uses.
Your comments are attributed to the collaborator who launched you and show up in
their rail exactly as if they had typed them.

## Rights boundary

You may **read** and **comment** only. You may not rewrite the plan
(`submit-revision` is the driving agent's alone), send the Message (`resolve` is
the human's alone), or cut / edit / share (owner-only). The plan stays
single-writer: you annotate, the human curates, the message carries it back.

Pass `--role agent` on every command below. The daemon then caps this connection
to read + annotate and rejects any escalation - the boundary is enforced, not
just documented.

## Steps

1. Read the artifact and its existing annotations:

   ```bash
   cueloop session get <id> --role agent
   ```

2. See the shared quick-action vocabulary for this session (the same presets the
   human picks); `--session` reads the reviewed session's own repo:

   ```bash
   cueloop actions list --session <id> --role agent
   ```

3. Comment on a span. **Anchor contract: `--quote` is the exact text from the
   artifact you are commenting on** - copy it verbatim, not a paraphrase or a
   line number. Add `--prefix`/`--suffix` (a few surrounding characters) when the
   quote is not unique. Attribute every comment to the acting collaborator with
   `--author` (and `--author-name` on the first comment so the rail shows a name):

   ```bash
   cueloop session annotate <id> --role agent \
     --author <collaborator-id> --author-name "<display name>" \
     --quote "<exact span from the plan>" \
     --body "<your comment>"
   ```

   To use a quick action instead of a free-form body, reference it by index or
   name from `actions list`:

   ```bash
   cueloop session annotate <id> --role agent \
     --author <collaborator-id> --quote "<exact span>" --action "Out of scope"
   ```

4. Type a comment with `--kind` for a typed annotation (`security`, `perf`, a
   tool id); the default kind is `comment`.