request_review

Get your own work read before you call it finished, which spawns the reviewer for you and hands you back the rest of the loop.

Agentwritesnot idempotentMCP tool

Commit on your branch first, since a review is given against a snapshot of your checkout as it stands. The reviewer is launched as your child, in your checkout, marked as a reviewer so it is briefed to read rather than to write, and named after you unless you pass a title. It runs on your workflow's harness unless harness names another CLI komrad knows, and takes the workflow's flags unless flags gives its own, which read the same way they do on create_agent. Your prompt is the whole briefing it gets, so say what the change is meant to do and where you are unsure of it rather than only naming a branch. agentId defaults to your own, which is in the KOMRAD_AGENT_ID environment variable. One reviewer reads every round of a change, so call this once: a second ask while that reviewer is still owed an answer is refused as already_exists, and what tells it there is more to read is you answering its threads with add_review_message. Pass idempotencyKey to make a retry safe, since a repeat of the call that spawned the reviewer is answered with that reviewer rather than refused. Once a reviewer has released an approval it is finished, so the next piece of work gets a reviewer of its own. Returns failed_precondition when the agent cannot hold a reviewer, which a child and a reviewer both cannot, and resource_exhausted when the panel has no room for another agent, which means to carry on and say so rather than to try again.

Calling it#

curl -X POST http://127.0.0.1:8787/agent.v1.AgentService/RequestReview \
  -H 'Content-Type: application/json' \
  -d '{
  "prompt": "<prompt>"
}'

komrad rpc request-review \
  --prompt <string>

{
  "name": "request_review",
  "arguments": {
    "prompt": "<prompt>"
  }
}

Offered by the komrad MCP server to implementer agents.

Request#

RequestReviewRequest#

Field	Type	Description
`prompt`	string	The whole briefing the reviewer is given, so it has to say what the change is meant to do and where the author is unsure of it. required, at most 50000 characters
`agentId`	string	Whose work to have read, or unset for the caller's own.
`title`	string	What to call the reviewer, blank to name it after the agent it is reading. at most 200 characters
`idempotencyKey`	string	A key that makes a retry safe, answering a repeat with the reviewer it already spawned rather than refusing it. at most 200 characters
`harness`	string	Which CLI the reviewer runs, blank to take the workflow's own. at most 40 characters, matching ^[a-z0-9-]*$
`flags`	string	Flags for the reviewer's CLI, blank to take the workflow's own. at most 500 characters

Response#

RequestReviewResponse#

Field	Type	Description
`reviewer`	Agent	The reviewer as spawned, which is a child of the agent being read.
`guidance`	string	What the agent that asked for the review does next, which is the rest of the loop it is in.

Types#

Agent#

Field	Type	Description
`id`	string	The handle every other call names this agent by, and what mail is addressed to.
`name`	string	What the panel lists it as, which is also its tmux window name at launch.
`cwd`	string	The directory it is running in, its own worktree when the workflow provisions one.
`flags`	string	The command-line flags its CLI was started with.
`prompt`	string	The whole briefing it was launched with.
`paneId`	string	The tmux pane its CLI is running in, which is what capture-pane reads.
`state`	AgentState	What the panel last decided it was doing, read off the tail of its pane.
`sessionId`	string	The CLI's own conversation id, which is the handle a resume needs.
`harness`	string	Which CLI it runs, such as claude or codex.
`workflowId`	string	Which workflow it is filed under, whose context it took at launch.
`createdAt`	string	When it was launched, in RFC 3339.
`archivedAt`	string	When it was hidden from the panel, unset while it is live.
`scheduleId`	string	The schedule that launched it, unset for an agent a person or another agent spawned.
`alive`	bool	Whether its pane is still there, which a dormant agent's is not.
`hidden`	bool	Whether the panel draws a row for it, which changes nothing about the agent itself.
`metadata`	list of AgentMetadata	Facts it has recorded about its own work, such as the ticket it is implementing.
`idempotencyKey`	string	The key a retry of its create carried, which is what answers a repeat with this agent.
`spawnedByAgentId`	string	Which agent called create, unset for one a person spawned.
`parentAgentId`	string	The agent this one is attached to, where spawned_by_agent_id is only who called create.
`branch`	string	The git branch its worktree is on, unset for an agent that provisions none.
`repositoryUrl`	string	The canonical web address of the repository its checkout pushes to, such as https://github.com/harrisoncramer/komrad, unset when the checkout is gone or its origin is not a forge.
`headSha`	string	The commit its checkout has checked out, unset when the checkout is gone or git cannot read it.
`worktreeRemoved`	bool	Whether its checkout has been taken away, which leaves the record and the transcript.
`sequenceInProgress`	bool	Whether a merge, a rebase or a cherry-pick is part-way through its checkout, waiting on somebody to settle it.
`failedRun`	bool	Whether a script komrad fired for the agent failed and nobody has looked at it since.
`failedRunLog`	int32	The run log that failure was written to, which is the run the panel opens on.
`stateChangedAt`	string	When the state above last moved, in RFC 3339.
`reportedReason`	string	What the agent's own CLI last reported it was doing, which annotates the state the pane decided rather than replacing it.
`role`	AgentRole	What the agent was launched to do, which decides the half of the review briefing it is sent.
`promptTruncated`	bool	Whether prompt holds only its opening, which a summary listing returns so that a page of agents does not carry every briefing they were launched with.
`treeStanding`	ReviewTreeStanding	Where the agent's worktree stood when last measured against the round tree_standing_sha names.
`treeStandingSha`	string	The snapshot of the round tree_standing was measured against, empty before any measurement.
`movedSinceRound`	string	The snapshot of its newest round while its worktree no longer hashes to it, empty otherwise.
`heldAt`	string	When a person stopped this agent and took its worktree, empty while nobody is holding it.

AgentMetadata#

Field	Type	Description
`key`	string	What the fact is filed under, such as pr or branch.
`value`	string	The fact as the panel shows it, which is why a URL belongs here whole.

AgentState#

AgentState is what the panel last decided an agent was doing, read off the tail of its pane.

Value	Description
`AGENT_STATE_IDLE`	The pane is at rest with nothing typed.
`AGENT_STATE_THINKING`	The CLI is working on a turn.
`AGENT_STATE_WAITING`	The CLI is blocked on a human answering a selection.
`AGENT_STATE_SETTING_UP`	The agent is being launched and has no pane to read yet.
`AGENT_STATE_FAILED_TO_CREATE`	The launch failed, which retry_agent is for.
`AGENT_STATE_FAILED_TO_CLEANUP`	A delete failed to take the worktree down, and the reason is on the row.
`AGENT_STATE_UNCERTAIN`	The pane could be read but its tail decided nothing.

AgentRole#

AgentRole is what an agent was launched to do.

Value	Description
`AGENT_ROLE_IMPLEMENTER`	An agent that lands work on a branch of its own.
`AGENT_ROLE_REVIEWER`	A child that reads another agent's work and gives a review.
`AGENT_ROLE_ORCHESTRATOR`	The agent drawn on a workflow's own row that hands work out.

ReviewTreeStanding#

ReviewTreeStanding is where an agent's worktree stands against the round its last verdict was given on.

Value	Description
`REVIEW_TREE_STANDING_MOVED`	The worktree differs from the round and the base does not hold the round.
`REVIEW_TREE_STANDING_LANDED`	The base holds the round whole and the worktree carries nothing beyond the base.
`REVIEW_TREE_STANDING_LANDED_MOVED`	The base holds the round whole and the worktree carries new work on top of the base.