---
title: "Comments & Review Kit"
description: "Inline comments, annotations, mentions, resolved threads, and review status surfaces."
---
# Comments & Review Kit
The Comments & Review Kit gives collaborative apps a standard review layer:
inline comments, canvas annotations, mentions, replies, resolved threads, and
status such as draft, review, approved, or needs changes.
## Pieces {#pieces}
| Piece | Purpose |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `registerReviewableResource()` | Register a resource type and optional access resolver for review actions. |
| Comment actions | `list-review-comments`, `create-review-comment`, `reply-review-comment`, `resolve-review-thread`, and `delete-review-comment`. |
| Feedback actions | `get-review-feedback`, `send-review-thread-to-agent`, and `consume-review-feedback` for root-thread agent queues and human handoffs. |
| Review status action | `set-review-status` for draft, in review, approved, and changes requested states. |
| `ReviewThreadPanel` | Drop-in React panel with capability-gated composer, reply, resolve, delete, and custom thread-action controls. |
| `ReviewStatusBadge` | Controlled status badge for app headers, sidebars, and review panels. |
| Review hooks | `useReviewComments()`, `useCreateReviewComment()`, `useReplyReviewComment()`, `useResolveReviewThread()`, `useDeleteReviewComment()`, and `useSetReviewStatus()`. |
| Mentions helpers | `extractReviewMentions()` and `normalizeReviewMentions()` for `@[Label](mailto:email@example.com)` tokens. |
## Shared Model {#shared-model}
Comments are resource-scoped, access-scoped, and agent-readable. The UI and
agent use the same actions to create, resolve, and list threads. Apps can
specialize anchor shapes, but the common model preserves:
- `resourceType` and `resourceId`
- `author`, `body`, `status`, and timestamps
- `parentCommentId` for replies
- optional `mentions`
- optional `anchor` or `resolutionTarget`
- optional `resolutionNote` on a resolved root thread
`list-review-comments` supports anonymous reads for resources whose access
resolver grants public viewer access. Public viewer responses redact ownership,
organization, email, and actor metadata while preserving safe display names and
the caller-specific `canDelete` capability. Its `summary` reports unpaginated
open-root and agent-queue counts even when the returned comment page is bounded.
## Register A Resource {#register-resource}
```ts
import { registerReviewableResource } from "@agent-native/core/comments-review";
registerReviewableResource({
type: "document",
async resolveAccess(resourceId, ctx) {
return {
role: "owner",
ownerEmail: ctx?.userEmail,
orgId: ctx?.orgId,
visibility: "private",
};
},
});
```
If the resource is already registered with the Sharing Kit, the review actions
reuse that access model. Add a review registration when the app needs a custom
access resolver or wants to make the resource type explicit in setup code.
## UI Usage {#ui-usage}
```tsx
import { ReviewThreadPanel } from "@agent-native/core/client/comments-review";
export function DocumentReview({ documentId }: { documentId: string }) {
return (
comment.canDelete === true}
/>
);
}
```
The `anchor` field is intentionally `unknown`: editors, canvases, diagrams, and
documents can store the shape they need while still using the shared review
actions and thread UI.
## UX Standard {#ux-standard}
- Comments live next to the thing being reviewed, not only in chat.
- Mentions resolve against team membership.
- Resolved threads remain visible in history.
- Agents can read open review feedback before changing code or content.
- `consumedAt` and `resolved` are separate. An agent can consume a piece of
feedback without closing the reviewer-visible thread.
- The root comment owns routing. A human-targeted root is absent from the agent
queue; sending it back to the agent clears its previous consumption marker.
- Agents can pass `resolutionNote` to `resolve-review-thread` so verification
evidence remains attached to the resolved root.
## What's next
- [**Plan**](/docs/template-plan) — a template that uses review threads for
plan feedback.
- [**Content**](/docs/template-content) — a template that uses review threads
for editorial approval.
- [**Sharing Kit**](/docs/toolkit-sharing) — the access model reviewable
resources can reuse.
- [**History Kit**](/docs/toolkit-history) — version history alongside the
review trail.