Reviewing an agent's work
Check an agent's work at the review, merge and verify stages. Read hand-off comments, open the merge request, or send work back for rework.
When an agent completes the build stage, it opens a merge request and posts a hand-off comment on the task. Before it advances to review, it waits for the request’s checks and fixes any failure. Review is the point where you read what the agent produced and decide what happens next: let it continue on its own, or send it back for rework.
This page is about one task at a time. To see how the review queue is doing overall — latency, how often work bounces back, and what review costs — see Review debt.
Reading an agent’s output
Hand-off comments
An agent’s hand-off comment is its own account of the work — what it did, the decisions it made, and anything it left open. Reading it before you open the merge request gives you context that the diff alone does not.
ch task show <taskId> --comments
This prints the full task details followed by the task’s comments, newest first. On a long history it prints one page and a note on how to see more. Hand-off comments are labelled with the stage they were posted in (for example, [hand-off @ code]) so you can tell which agent wrote what and when. See Task comments and hand-off notes for how that stamp gets there and what it means for the next stage’s brief.
The merge request
The code stage gate requires the build agent to fill the artifact field before the task can advance. Fetch it with:
ch task fields show <taskId> artifact
This prints the link. Open it in your browser to read the diff, check CI results, and review the agent’s pull request description.
When the link is a pull request or merge request, CodeHerder also records it as the task’s merge request for that repo, unless the repo already has one. You don’t need to record it again.
By default, the commits in it name the person who filed the task as author and the agent as committer. See Whose name is on a commit.
Before you dive into the diff, the task’s own page also shows its change shape — how many files and lines it touches, and how spread out it is — a quick signal for whether this is a small, focused review or one worth asking to be split up. On a task working in more than one repository, the shape breaks down by repo too. See Change shape for what the numbers mean.
Confirming it merged
A task keeps one list of merge requests. It holds every request the task’s sessions opened, and it marks the ones the task waits on before it counts as landed, one per repo. List them with:
ch task merge-requests <taskId>
When the task waits on at least one request, the first line reads “N of M merged” and counts those requests. Each row then shows the request’s number, title and link, whether the task waits on it (AWAITED), and its state: open, merged or closed. The row also carries what the git host last reported — draft, review decision, approvals, pipeline and mergeability — or none when it reported nothing. set-merge-ref and clear-merge-ref still work as older names for its create and delete.
Built-in workflows don’t need you to manage this: the merge stage lands the request, and CodeHerder moves the task on once every request it waits on has merged. Record one yourself when a task works in more than one repository and a repo’s request is missing, or when a workflow has a stage built to wait for someone else to merge the change — see Integrations for what a connected GitHub or GitLab account adds there:
ch task merge-requests create <taskId> <pr-or-mr-url>
Recording a second URL for a repo you’ve already recorded updates that repo’s request instead of adding a duplicate; a URL for a different repo adds a new one. If you record a stray or mistyped URL, remove it with:
ch task merge-requests delete <taskId> <pr-or-mr-url>
Deleting stops the task from waiting on that request. A request one of the task’s sessions opened stays in the list, no longer marked awaited.
The state can lag your git host. When it matters, open the request itself to check whether it has landed. An inbound webhook rule can report a merge outcome from your git host back to the task.
ch task show <taskId> prints a summary line when the task waits on at least one request, followed by one line per awaited request:
merge refs: 1 of 2 merged
https://github.com/acme/my-app/pull/123 (merged Nov 14 10:22)
https://gitlab.com/acme/my-lib/-/merge_requests/45 (unmerged)
The merge time shows in your local time zone. A merge from today shows the time only, such as (merged 14:05:12).
On the web app, the task page has a Merge requests panel. Each row shows its state — open, merged or closed — and an Awaited badge marks the ones the task waits on. See Tasks that span several repositories for the full model.
The review checkpoint
review runs its own agent. The review agent reads the merge request’s diff and the task’s acceptance criteria, then takes one of two actions:
- Approve — it moves the task to
merge. It doesn’t merge anything itself; the merge agent does that next. - Reject — it posts a comment saying what must change, then sends the task back to
code. That send-back counts against the round cap described below.
The review agent doesn’t approve while any acceptance criterion is unmet. You don’t have to wait for it, though: read the same diff yourself, and send the task back if you disagree — see Sending work back for rework below.
Approval gates at review, merge, and verify
By default, CodeHerder moves work through review, merge, and verify without waiting for human input — each stage’s agent finishes its check and hands the task to the next one automatically. If you’re satisfied with what you see, there’s nothing to do.
An admin can put an approval gate on any of these stages. The hand-off out of a gated stage then waits as a pending request until an eligible member runs ch task approve <taskId> or ch task reject <taskId>. See Approvals and staying in control for how gates work and who can approve.
The merge checkpoint
merge is the stage between review and verify where an agent lands the merge request on the task’s base branch (see Choosing a task’s base branch), and by default it needs nothing from you either: the merge agent confirms the request’s checks are green, merges it, and advances the task on its own. While the checks are still running, it parks the task on the request and CodeHerder wakes it when they finish, so the task can sit at merge for a while without anything being wrong.
If it can’t land the change as-is, it doesn’t stop and wait for you — it acts:
- Conflict or a red pipeline caused by its own change — it resolves the conflict or fixes the failure itself, then merges.
- The work genuinely needs to change — it hands the task back to
codewith a comment describing what must change, the same as a reviewer sending work back. - Landing needs something no agent can grant — most often a required human approval on the request — it files a blocker instead, which is where you’ll see it.
You can tell which happened from the task’s activity and comments:
ch task show <taskId> --comments
If the task came back to code, you’ll see a hand-off comment from the merge agent explaining what to change — inspect it the same way you would a review send-back. If it’s sitting at blocked, check Blockers and blocked tasks for what to do next. See How work flows for the full mechanics behind the merge stage.
The verify checkpoint
verify is the last stop before a task closes, and by default it needs nothing from you: the verify agent exercises the merged change and takes one of two actions on its own —
- Pass — the task advances straight to
done. - Fail — the task goes back to
codefor rework, with a comment explaining what did not work.
A pass takes two records, and the verify agent writes both. It fills the task’s verification field with proof: the merge commit on the base branch, plus a one-line confirmation that the change works. It also records a pass for the stage’s required verification on the current attempt. A feature, bug, or story can’t move from verify to done until both are in place. Not every task passes through verify on its way to done, though: completing a task early from an earlier stage, or a lightweight task type that has no verify stage in its pipeline at all, can still close without it. See How work flows for how the field and the verification gate the move to done.
You can still inspect what verify found:
ch task show <taskId> --comments
shows any comment the verify agent left — for example, an explanation of what failed.
ch task verifications <taskId>
lists every verification result recorded for the task, most recent first — 50 to a page, so see Paging through long lists if a task has bounced back and forth enough to need more. Each row names the stage and attempt it belongs to, its status, when it was recorded, and who recorded it — including the pass or fail the verify agent itself recorded.
If you want to catch a problem before the task closes, or you disagree with a pass, send it back the same way you would from review — see Sending work back for rework below.
Sending work back for rework
If the build does not meet the acceptance criteria, send the task back to the build stage:
ch task status <taskId> code --reason "what must change"
Include a --reason explaining what is wrong and what the agent should do differently. The next build session starts with that note as part of its brief.
Two things happen automatically when you send a task back:
- Model escalation. CodeHerder escalates to a more capable model for the next build attempt — the first attempt runs on the standard tier; any subsequent rework runs on the more capable tier. See How work flows for the full escalation details.
- Round cap.
codesets one cap number for how many times it can be re-entered, but each send-back edge into it —review → code,merge → code,verify → code— counts toward that same number independently. The task blocks the moment any single edge reaches the cap, not when the edges’ counts add up to it. CodeHerder moves the task toblockedand files a blocker note explaining how many times it bounced. A human then reviews the situation and either resumes the task or cancels it. See How work flows for the default cap value.
If code isn’t far enough back — the work needs rethinking from the plan, say — use ch task reopen instead. It reaches further, and it also works from a task that’s already done, cancelled, or archived. The round cap never refuses a reopen. But a reopen that moves a still-active task (at review, merge, or verify) back to code still adds to the running count the cap checks. Only a reopen of a task that’s already closed stays out of that count. It needs a --reason, and only a human can run it. See Reopening a cancelled or completed task in Editing and cancelling tasks.
The difference between sending back and rejecting
Three commands can look similar but do entirely different things:
| Command | What it does |
|---|---|
ch task status <taskId> code --reason "..." |
Moves the task from review, merge, or verify back to the build stage. A new build session starts. |
ch task reopen <taskId> <stage> --reason "..." |
Sends the task back further than the build stage — to plan, say — including from done, cancelled, or archived after it has already closed. The round cap never refuses it — see Sending work back for rework above for when it still counts toward the cap. |
ch task reject <taskId> |
Rejects a pending approval request on a gated stage. The task stays exactly where it is — nothing starts or restarts. |
Use ch task status <taskId> code when you have reviewed the work and decided it needs changes. Use ch task reopen when you need to reach further back than that, or the task has already finished. ch task reject <taskId> is unrelated to sending a build back: it only answers a pending approval request, and it applies on any gated stage. See Approvals and staying in control for how it works.
Related guides
- How work flows — the stages every task moves through
- Writing tasks an agent can build — how to file work agents can pick up
- Assigning and claiming work — who ends up working a task
- Approvals and staying in control — gate advances behind a designated approver
- Why isn’t my task moving? — diagnose a stuck task
- Review debt — how the review queue is doing across the whole workspace
- Change shape — how big and spread out a task’s change is, and the optional per-stage limit
- Tasks that span several repositories — one task, several repos, several merge requests
- Integrations — connect GitHub or GitLab so a workflow stage built to wait for an external merge can check it
- Inbound webhooks — let your git host report a merge outcome back to the task
Last updated