pm_review
{"content":"{{\u003c tier level=\"vanguard\" \u003e}} {{\u003c tier level=\"sovereign\" label=\"Some actions: Sovereign\" \u003e}}\n\nThe `pm_review` tool orchestrates task review workflows. Reviews are how completed work gets evaluated before it ships — you start a review on a task, assign reviewer agents, launch them against the work, publish findings, and optionally record lightweight review scores. Auditor workflows and audit score runs live in [`pm_audit`](../audits/).\n\n## Actions\n\n`start`, `list`, `delete`, `update_assignment`, `comment`, `comment_list`, `comment_delete`, `verify_ready`, `publish`, `get_prompt`, `launch_reviewer`, `statuses`, `score_record`, `score_list`, `help`\n\n### Sovereign-only actions\n\nThe following actions require the **Sovereign** tier — they are not available at Vanguard:\n\n- `launch_reviewer` — launches an agent session\n\n---\n\n## start\n\nStart a review for a task.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | Yes | |\n| `reviewerHandle` | string | Conditional | Single reviewer handle (preferred). Required if `reviewerHandles` is omitted. |\n| `reviewerHandles` | string[] | Conditional | Multi-reviewer alternative. Required if `reviewerHandle` is omitted. |\n| `requestedByHandle` | string | No | Who requested the review (defaults to actor) |\n| `summary` | string | No | What's being reviewed |\n| `actorHandle` | string | Yes | Actor handle |\n| `clientRequestId` | string | No | Stable request ID for creating this review; reuse with the same reviewers and summary on retry |\n\n### Example\n\n```text\npm_review {\n action: \"start\",\n taskKey: \"MYAPI-42\",\n reviewerHandle: \"sigrid\",\n actorHandle: \"@alice\",\n requestedByHandle: \"alice\",\n summary: \"Rate limiting implementation ready for review\"\n}\n```\n\n---\n\n## list\n\nList reviews for a task.\n\nA successful response with `reviews: []` means the task has no matching reviews. It is not a tool failure.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n| `reviewerHandle` | string | No |\n| `status` | string | No |\n\n---\n\n## delete\n\nDelete a review.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n| `reviewId` | string | Yes |\n| `actorHandle` | string | No |\n\n---\n\n## update_assignment\n\nUpdate reviewer assignment status.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `reviewId` | string | Yes |\n| `assignmentId` | string | Yes |\n| `status` | string | Yes |\n| `feedback` | string | No |\n| `actorHandle` | string | No |\n\n---\n\n## comment / comment_list / comment_delete\n\nManage review comments. Comments can be threaded via `parentCommentId`.\n\n### comment\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | Yes | |\n| `body` | string | Yes | |\n| `reviewId` | string | No | |\n| `assignmentId` | string | No | |\n| `parentCommentId` | string | No | For threaded replies |\n| `actorHandle` | string | No | |\n\n### comment_list\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n| `reviewId` | string | No |\n| `assignmentId` | string | No |\n\n### comment_delete\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n| `commentId` | string | Yes |\n| `actorHandle` | string | No |\n\n---\n\n## verify_ready\n\nCheck whether any task review remains unapproved. The result contains `canVerify` and `pendingStatuses`; it does not change task status or independently inspect score records. A task with no reviews also returns `canVerify: true`, so inspect `list` if your process requires a completed review.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n\n---\n\n## publish\n\nPublish a review — combines comment, status, and score in one operation.\n\nRecommendations are intentionally narrow: use only `ready`, `changes_requested`, or `reject`. Do not send older recommendation labels or status-like values.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | Yes | |\n| `body` | string | Yes | Review comment body |\n| `scoredHandle` | string | Yes | Handle of agent being scored |\n| `score` | number | Yes | Score 0–100 |\n| `reviewId` | string | No | Review to publish to (auto-detected if omitted) |\n| `assignmentId` | string | No | Requires `reviewId` |\n| `status` | string | No | Desired status (inferred from body/recommendation) |\n| `recommendation` | string | No | `ready`, `reject`, or `changes_requested` |\n| `feedback` | string | No | Additional feedback text |\n| `scoreNotes` | string | No | Notes for the score |\n| `actorHandle` | string | No | |\n\n### Example\n\n```text\npm_review {\n action: \"publish\",\n taskKey: \"MYAPI-42\",\n body: \"Implementation looks clean. Tests cover edge cases well.\",\n scoredHandle: \"claude-coder\",\n score: 92,\n actorHandle: \"sigrid\",\n recommendation: \"ready\"\n}\n```\n\n---\n\n## get_prompt\n\nFetch review prompts for a reviewer.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | Yes | |\n| `reviewerHandle` | string | Conditional | Required if multiple reviewers |\n\n---\n\n## launch_reviewer\n\nLaunch a reviewer agent session attached to an existing worktree.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `clientRequestId` | string | Yes | Idempotency key |\n| `actor` | string | Yes | Actor string (e.g., `\"@pm\"`) |\n| `taskKey` | string | Yes | |\n| `sourceSessionUlid` | string | Yes | Session whose worktree is being reviewed |\n| `agentId` / `agentHandle` | string | No | Specific reviewer |\n| `provider` | string | No | Provider override |\n| `launcherConfigKey` | string | No | Preset override |\n| `prompt` | string | No | Initial user message override (skill mode) |\n| `systemPrompt` | string | No | System prompt override |\n| `config` | object | No | Provider config overrides |\n| `role` | string | No | Role (default `reviewer`) |\n| `capabilityKeys` | string[] | No | |\n| `additionalInstructions` | string | No | |\n| `maxRuntimeSeconds` | number | No | |\n| `run` | boolean | No | Run immediately (default `true`) |\n\n### Example\n\n```text\npm_review {\n action: \"launch_reviewer\",\n clientRequestId: \"01HXYZ...\",\n actor: \"@skadi\",\n taskKey: \"MYAPI-42\",\n sourceSessionUlid: \"01HABC...\",\n agentHandle: \"sigrid\",\n launcherConfigKey: \"reviewer-claude\"\n}\n```\n\n---\n\n## statuses\n\nList available review statuses. Takes no parameters.\n\n```text\npm_review { action: \"statuses\" }\n```\n\n---\n\n## score_record\n\nRecord a lightweight review score that stays attached to the task review record. This is different from audit score runs in `pm_audit`.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n| `scoredHandle` | string | Yes |\n| `score` | number | Yes |\n| `reviewId` | string | No |\n| `assignmentId` | string | No |\n| `scoreNotes` | string | No |\n| `actorHandle` | string | No |\n\n---\n\n## score_list\n\nList lightweight review scores for a task.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n| `reviewId` | string | No |\n| `assignmentId` | string | No |\n\n---\n\n## help\n\n```text\npm_review { action: \"help\" }\n```\n\n`help` returns structured, read-only guidance for review lifecycle automation.\n\n| Field | Contents |\n|-------|----------|\n| `actions` | Current accepted action names, including `update_assignment`, `comment_delete`, `launch_reviewer`, `score_record`, `score_list`, and `help` |\n| `whenToUse` | Guidance for review creation, listing, assignment updates, comments, publishing, verification checks, reviewer launches, and lightweight scores |\n| `examples` | Representative calls for listing reviews, publishing a `ready` recommendation, and checking `verify_ready` |\n| `cautions` | Guardrails such as not moving executor tasks directly to `verified`, resuming reviewer sessions before launching duplicates, and including actor metadata |\n| `compatibility` | Notes on review comments and task-thread context |\n\nUse this payload when agents need to decide whether to resume review work, publish a recommendation, or check the verification gate.\n\n## Related\n\n- [Reviewable AI Agent Workflows](/valdr/docs/features/reviewable-workflows/) — product-level overview of evidence-backed review, audit, and approval gates\n- [pm_audit](../audits/) — dedicated auditor launch, evidence, and audit score-run surface\n- [pm_session](../sessions/) — underlying session mechanics\n- [pm_task](../tasks/) — reviews are attached to tasks","description":"Review lifecycle: start reviews, assign reviewers, launch reviewer agents, publish findings, and record lightweight review scores.","title":"pm_review"}
Vanguard
Some actions: Sovereign
The pm_review tool orchestrates task review workflows. Reviews are how completed work gets evaluated before it ships — you start a review on a task, assign reviewer agents, launch them against the work, publish findings, and optionally record lightweight review scores. Auditor workflows and audit score runs live in pm_audit.
Actions
start, list, delete, update_assignment, comment, comment_list, comment_delete, verify_ready, publish, get_prompt, launch_reviewer, statuses, score_record, score_list, help
Sovereign-only actions
The following actions require the Sovereign tier — they are not available at Vanguard:
launch_reviewer— launches an agent session
start
Start a review for a task.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
taskKey | string | Yes | |
reviewerHandle | string | Conditional | Single reviewer handle (preferred). Required if reviewerHandles is omitted. |
reviewerHandles | string[] | Conditional | Multi-reviewer alternative. Required if reviewerHandle is omitted. |
requestedByHandle | string | No | Who requested the review (defaults to actor) |
summary | string | No | What’s being reviewed |
actorHandle | string | Yes | Actor handle |
clientRequestId | string | No | Stable request ID for creating this review; reuse with the same reviewers and summary on retry |
Example
pm_review {
action: "start",
taskKey: "MYAPI-42",
reviewerHandle: "sigrid",
actorHandle: "@alice",
requestedByHandle: "alice",
summary: "Rate limiting implementation ready for review"
}list
List reviews for a task.
A successful response with reviews: [] means the task has no matching reviews. It is not a tool failure.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
reviewerHandle | string | No |
status | string | No |
delete
Delete a review.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
reviewId | string | Yes |
actorHandle | string | No |
update_assignment
Update reviewer assignment status.
Parameters
| Field | Type | Required |
|---|---|---|
reviewId | string | Yes |
assignmentId | string | Yes |
status | string | Yes |
feedback | string | No |
actorHandle | string | No |
comment / comment_list / comment_delete
Manage review comments. Comments can be threaded via parentCommentId.
comment
| Field | Type | Required | Notes |
|---|---|---|---|
taskKey | string | Yes | |
body | string | Yes | |
reviewId | string | No | |
assignmentId | string | No | |
parentCommentId | string | No | For threaded replies |
actorHandle | string | No |
comment_list
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
reviewId | string | No |
assignmentId | string | No |
comment_delete
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
commentId | string | Yes |
actorHandle | string | No |
verify_ready
Check whether any task review remains unapproved. The result contains canVerify and pendingStatuses; it does not change task status or independently inspect score records. A task with no reviews also returns canVerify: true, so inspect list if your process requires a completed review.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
publish
Publish a review — combines comment, status, and score in one operation.
Recommendations are intentionally narrow: use only ready, changes_requested, or reject. Do not send older recommendation labels or status-like values.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
taskKey | string | Yes | |
body | string | Yes | Review comment body |
scoredHandle | string | Yes | Handle of agent being scored |
score | number | Yes | Score 0–100 |
reviewId | string | No | Review to publish to (auto-detected if omitted) |
assignmentId | string | No | Requires reviewId |
status | string | No | Desired status (inferred from body/recommendation) |
recommendation | string | No | ready, reject, or changes_requested |
feedback | string | No | Additional feedback text |
scoreNotes | string | No | Notes for the score |
actorHandle | string | No |
Example
pm_review {
action: "publish",
taskKey: "MYAPI-42",
body: "Implementation looks clean. Tests cover edge cases well.",
scoredHandle: "claude-coder",
score: 92,
actorHandle: "sigrid",
recommendation: "ready"
}get_prompt
Fetch review prompts for a reviewer.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
taskKey | string | Yes | |
reviewerHandle | string | Conditional | Required if multiple reviewers |
launch_reviewer
Launch a reviewer agent session attached to an existing worktree.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
clientRequestId | string | Yes | Idempotency key |
actor | string | Yes | Actor string (e.g., "@pm") |
taskKey | string | Yes | |
sourceSessionUlid | string | Yes | Session whose worktree is being reviewed |
agentId / agentHandle | string | No | Specific reviewer |
provider | string | No | Provider override |
launcherConfigKey | string | No | Preset override |
prompt | string | No | Initial user message override (skill mode) |
systemPrompt | string | No | System prompt override |
config | object | No | Provider config overrides |
role | string | No | Role (default reviewer) |
capabilityKeys | string[] | No | |
additionalInstructions | string | No | |
maxRuntimeSeconds | number | No | |
run | boolean | No | Run immediately (default true) |
Example
pm_review {
action: "launch_reviewer",
clientRequestId: "01HXYZ...",
actor: "@skadi",
taskKey: "MYAPI-42",
sourceSessionUlid: "01HABC...",
agentHandle: "sigrid",
launcherConfigKey: "reviewer-claude"
}statuses
List available review statuses. Takes no parameters.
pm_review { action: "statuses" }score_record
Record a lightweight review score that stays attached to the task review record. This is different from audit score runs in pm_audit.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
scoredHandle | string | Yes |
score | number | Yes |
reviewId | string | No |
assignmentId | string | No |
scoreNotes | string | No |
actorHandle | string | No |
score_list
List lightweight review scores for a task.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
reviewId | string | No |
assignmentId | string | No |
help
pm_review { action: "help" }help returns structured, read-only guidance for review lifecycle automation.
| Field | Contents |
|---|---|
actions | Current accepted action names, including update_assignment, comment_delete, launch_reviewer, score_record, score_list, and help |
whenToUse | Guidance for review creation, listing, assignment updates, comments, publishing, verification checks, reviewer launches, and lightweight scores |
examples | Representative calls for listing reviews, publishing a ready recommendation, and checking verify_ready |
cautions | Guardrails such as not moving executor tasks directly to verified, resuming reviewer sessions before launching duplicates, and including actor metadata |
compatibility | Notes on review comments and task-thread context |
Use this payload when agents need to decide whether to resume review work, publish a recommendation, or check the verification gate.
Related
- Reviewable AI Agent Workflows — product-level overview of evidence-backed review, audit, and approval gates
- pm_audit — dedicated auditor launch, evidence, and audit score-run surface
- pm_session — underlying session mechanics
- pm_task — reviews are attached to tasks