Reviewing an agent's work

When an agent completes the build stage, it opens a merge request and posts a hand-off comment on the task before advancing to review. This 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 every comment, newest first. 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.

The merge request

The code stage gate requires the build agent to record the merge request URL before the task can advance. Fetch it with:

ch task field <taskId> artifact

This prints the URL. Open it in your browser to read the diff, check CI results, and review the agent’s pull request description.

Confirming it merged

The artifact field is just a link — it doesn’t tell you whether the request behind it has actually merged. To have CodeHerder track that for you, record the same link as the task’s merge ref, at review time or any point before the task reaches its merge stage:

ch task set-merge-ref <taskId> <pr-or-mr-url>

From then on, CodeHerder tracks that request and keeps its merged/unmerged state current on its own — no need to reopen the request or run the command again. This is the quickest way to confirm a change has landed, without leaving your terminal.

ch task show <taskId>

includes a line like:

merge ref:   https://github.com/acme/my-app/pull/123  (merged 2 hours ago)

or (unmerged) if it has not landed yet. On the web app, the task page shows the same information as a Merge ref row, with the request linked and a badge reading merged or unmerged.

Approval gates don’t pause review, merge, or 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; the task keeps advancing on its own.

Approval gates don’t reach into that hand-off. A gate only intercepts CodeHerder’s own automatic advance into a stage, and for the built-in feature, bug, and story types that only ever happens once — moving an unassigned task out of todo, before any agent has started it. The review → merge, merge → verify, and verify → done hand-offs are each made explicitly by the agent working that stage, so a gate on review, merge, or verify has nothing to intercept, and ch task approve <taskId> never comes up at these checkpoints. See Approvals & staying in control for where gates do apply.

If you want a checkpoint at one of these stages, inspect the work after the fact and send it back if something’s wrong — see Sending work back for rework below — rather than relying on a gate to pause before it happens.

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 code for rework, with a comment explaining what did not work.

A pass also records proof that the change works directly on the task — this is filled in automatically by the agent, never by a human, and the task cannot reach done without it. See How work flows for how that proof gates 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, 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. The review→code and verify→code loops each have a configurable cap. When the cap is reached, CodeHerder moves the task to blocked and 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 values.

The difference between sending back and rejecting

Two commands can look similar but do entirely different things:

Command	What it does
ch task status <taskId> code --reason "..."	Moves the task from review or verify back to the build stage. A new build session starts.
ch task reject <taskId>	Rejects a pending approval-gate advance only. 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. ch task reject <taskId> is unrelated to reviewing a build — it only comes into play if a task type’s entry stage is gated and a pending-advance request is waiting, before any agent has started the task. See Approvals & staying in control for more on the pending-advance state and how ch task reject 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 & 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