Commenting Back on Agent Work

Comments are how you review and guide an agent during a session. The mechanics (anchoring, threading, origin tagging, resolution) are universal and live in Comments. This page is the agent-specific layer: what to look for in the UI, and how to write feedback an agent can actually act on.

What you'll see

When an agent is working on an artifact:

• Agent's runtime name as the author on every comment it posts (e.g. claude or codex). You tell agent posts from your own by the author name, not by a special badge.

• Activity badge in place of the reply input while the comment is in flight. Two states:

  • Waiting for agent… (gray) right after a comment is routed but before the agent has claimed it.
  • Being addressed… (blue) once the agent calls artifact_comment_claim with a short note describing the work ("Rewriting the migration to drop-before-create", "Adding a null check in the validator", etc.). Click the badge to jump to the running session.
• Nevermind button alongside both badge states. Click it to cancel — Spruce posts a status line on the thread and stops the agent via a [reply-cancelled] PTY tag. The badge clears and you're free to re-route or resolve.
• Auto-release when the agent replies — the badge clears and the reply is in the thread.

If the action that launched the agent has forward: [comment-added] in its frontmatter, your replies are auto-forwarded into the running session, so the agent reads them on its next prompt without needing a re-launch. If no session is listening (yet, or after a Nevermind), a small Choose how to handle this comment menu appears under the reply box with one-click options to send to a running session or start a new action.

See Comments → Routing comments to agents for the full mechanics, and Actions → Anatomy of an action for the forward: field.

Artifact editor with agent and user comments threaded on a paragraph; one with a "being addressed" spinner

The cycle

1. You post or reply to a comment. Either it's auto-forwarded into a listening session, or you pick a target from the route menu. Badge enters Waiting for agent….
2. Agent claims via artifact_comment_claim with a one-line note. Badge flips to Being addressed… with the note shown inline.
3. Agent works.
4. Agent replies → claim auto-releases → badge clears.
5. You read the reply, then either resolve the thread, reply with further direction, or click Nevermind to cancel the next pass.
6. If you reply, the agent re-claims on its next pass and the cycle restarts.

For the underlying tools (artifact_comment_claim, artifact_comment_reply, artifact_comment_resolve), see MCP Tools.

Writing review comments agents can act on

Agents can't see your screen — they only have what you wrote and the artifact's content. Three rules of thumb that significantly improve iteration quality:

• Be specific. Reference the exact section, function, or line you want changed. "Rewrite the validator's null check to handle the array case" lands better than "the validator is wrong."
• Explain why, not just what. "Rename resolve → close for clarity, since resolve collides with promise terminology" gives the agent the principle, not just the rule. The next ambiguous case gets handled correctly without a follow-up comment.
• One ask per comment. Splitting feedback into separate comments makes it easier for the agent to address them independently, and easier for you to resolve threads as they're handled.

Resolving

Resolution is under your control. The agent can post replies but can't re-open a resolved thread. Use Resolve when the work is to your satisfaction; reply again if the agent's response only partially addresses the comment.

Related

• Comments — the canonical doc on the comment system, including anchoring, origin tags, and storage.
• MCP Tools — artifact_comment_claim, artifact_comment_reply, artifact_comment_resolve.
• Hand Work to an Agent — kicking off the agent in the first place.
• Actions — how agents get launched in the first place.