create_review_thread

Pin a comment to a place in another agent's diff, which is how you give it a review rather than mailing it prose.

Agentwritesnot idempotentMCP tool

You may only review the agent you are a child of. The comment is filed under a batch of your own that nobody sees until you release it with release_review, so write every comment you have and then release once. Anchor it with the file and the line range from the round you are reviewing, and pass the diff lines you are writing about as quotedLines so the anchor still says something after the code moves. Pass snapshotSha, which is the snapshot of the round you are reading, so the comment is filed against the code you counted the lines off rather than against whatever round is newest. Pass suggestion to propose exact replacement lines the agent should apply. Write it the way you would say it out loud. One or two sentences is the normal size and a hundred words is the ceiling. Name the line, the value or the case you mean, and quote code where the code is the point. No preamble, no summary at the end, no hedging, and no invented names for things the repository does not call that. Say what is wrong and what to do about it. Each call opens another thread, so do not retry a call that may have succeeded.

Calling it#

curl -X POST http://127.0.0.1:8787/agent.v1.AgentService/CreateReviewThread \
  -H 'Content-Type: application/json' \
  -d '{
  "agentId": "<agentId>",
  "filePath": "<filePath>",
  "body": "<body>"
}'

komrad rpc create-review-thread \
  --agent-id <string> \
  --file-path <string> \
  --body <string>

{
  "name": "create_review_thread",
  "arguments": {
    "agentId": "<agentId>",
    "filePath": "<filePath>",
    "body": "<body>"
  }
}

Offered by the komrad MCP server to reviewer agents.

Request#

CreateReviewThreadRequest#

Field	Type	Description
`agentId`	string	Whose diff to pin the comment to. required
`filePath`	string	Which file, relative to the checkout. required
`baseSha`	string	The commit the old side of these line numbers was read against, empty for the round's own base.
`snapshotSha`	string	The commit the new side of these line numbers was read against, empty for a caller that read the round's own snapshot.
`oldStart`	int32	Where the range begins on the old side of the diff, counting from one.
`oldEnd`	int32	Where it ends on the old side, inclusive.
`newStart`	int32	Where the range begins on the new side.
`newEnd`	int32	Where it ends on the new side, inclusive.
`quotedLines`	list of string	The diff lines being written about, each keeping its leading marker, so the anchor still says something once the code moves.
`body`	string	The first thing said. The ceiling refuses an essay and is not a length to write up to. required, at most 1000 characters
`suggestion`	list of string	Replacement lines proposed for the range, empty for an ordinary comment.

Response#

CreateReviewThreadResponse#

Field	Type	Description
`thread`	ReviewThread	The thread as opened, private until the batch is released.

Types#

ReviewThread#

ReviewThread is one conversation pinned to a place in a round of an agent's diff.

Field	Type	Description
`id`	string	The handle a reply or a resolve names this thread by.
`agentId`	string	Whose diff the thread is pinned to.
`reviewId`	string	The batch this thread was opened as part of.
`roundId`	string	The round the thread is anchored to, which never moves.
`roundOrdinal`	int32	Which round that is, counting from one.
`baseSha`	string	The commit the old side of these line numbers was read against, which is the round's own base unless the diff was narrowed to an earlier round when the thread was written.
`filePath`	string	Which file, relative to the checkout.
`oldStart`	int32	Where the range begins on the old side of the diff, counting from one.
`oldEnd`	int32	Where it ends on the old side, inclusive.
`newStart`	int32	Where the range begins on the new side.
`newEnd`	int32	Where it ends on the new side, inclusive.
`quotedLines`	list of string	The diff lines the thread was written against, each keeping its leading marker.
`resolvedAt`	string	When the person reviewing settled this thread, empty while it is still owed an answer. Whether a thread is settled is a different question from whether the code under it has moved, and it is this one that decides whether the thread is still asking for something.
`unreadByHuman`	bool	Whether the agent has replied since the person reviewing last looked.
`messages`	list of ReviewMessage	Everything said in the thread, oldest first.
`createdAt`	string	When the thread was opened.
`updatedAt`	string	When anything in it last moved.

ReviewMessage#

ReviewMessage is one thing said in a review thread.

Field	Type	Description
`id`	string	The handle an edit of this message names it by.
`threadId`	string	Which conversation it belongs to.
`authorKind`	ReviewAuthorKind	Whether a person or an agent wrote it.
`authorAgentId`	string	The agent that wrote it, absent for the person reviewing and cleared if that agent is deleted. author_kind, not this, is what says who wrote it.
`body`	string	What the author wrote.
`suggestion`	list of string	Replacement lines the author proposes for the thread's range, empty for an ordinary comment. An agent applies these rather than reasoning about them.
`createdAt`	string	When it was written.
`updatedAt`	string	When it was last edited.
`delivery`	ReviewDeliveryState	How far this comment has got towards the agent reading it.
`sentAt`	string	When the person reviewing released this comment, empty while it is only written down.
`deliveredAt`	string	When the agent claimed the doorbell raised for this comment, empty until it has.
`reviewId`	string	The review this message went out with, absent for an answer written by the agent under review, which belongs to no batch.

ReviewAuthorKind#

ReviewAuthorKind is who wrote a review message.

Value	Description
`REVIEW_AUTHOR_KIND_HUMAN`	The person running komrad.
`REVIEW_AUTHOR_KIND_AGENT`	The agent whose work is being read, or the reviewer reading it.

ReviewDeliveryState#

ReviewDeliveryState is how far one of the person's comments has got towards the agent reading it. It is no stored field: it is read off the comment's own sent stamp and the newest doorbell raised against it, since the stamp outlives mail the agent deletes or lets expire. Whether the comment has been answered is a different question, read off the messages of the thread.

Value	Description
`REVIEW_DELIVERY_STATE_UNSENT`	Written down and not yet let go of.
`REVIEW_DELIVERY_STATE_SENT`	Released, with a doorbell still waiting to be claimed.
`REVIEW_DELIVERY_STATE_DELIVERED`	Released, and the agent has claimed the doorbell.