Shared Review Surface
When a human and a coding agent both annotate the same line-anchored review artifact — a diff, with notes pinned to specific files and lines — that artifact stops being a one-way report and becomes a two-way communication channel. The move has two directions that are usually treated as separate tools but here share one surface:
- Agent → human. The agent writes review notes onto the diff, anchored to the line they concern ("worker/index.ts:25 — KV increments can lose concurrent updates"), and the human reads them in place while reviewing, rather than as a separate wall of prose.
- Human → agent. The human writes notes onto lines of
the diff ("add a button for the reset API" on
src/App.tsx), and the agent reads those notes back and turns them into edits — without the human re-describing where or what in a chat box.
The load-bearing idea is that location is part of the message. A comment pinned to a line carries its own context, so a line-anchored annotation is a lower-ambiguity channel than prose chat about "that function" — neither party has to re-establish where. The review view, which already exists to make agent output legible (Agent Supervision), doubles as the workspace where instructions flow the other way.
The enabling mechanism is a shared annotation store both
parties can read and write. In the motivating demo (Hunk) this
is a live diff "session" the agent reaches through a loaded skill that
wraps a CLI (CLI Tools over MCP
Servers): the agent runs hunk skill path to load the
skill, then hunk session comment list to read/write
comments against the live session, while the human edits the same
comments in the TUI and refreshes to see the agent's. The skill is the
seam that makes the surface symmetric; without agent read and
write access it collapses back to a one-way report.
Claims
- A review artifact can be the collaboration medium: when human and agent annotate the same line-anchored diff, review becomes a two-way channel, not a one-way report. principle — durable: once both parties can write to the same surface, the diff carries instructions in both directions, not just the agent's output down to the human.
- Location is part of the message — a note pinned to a line carries its own context, so line-anchored annotations are a lower-ambiguity channel than prose chat. principle — durable: it removes the re-establish-where step that a separate chat box forces on every comment; this holds independent of the particular tool.
- Give the agent symmetric read and write access to
the annotation store (via a loaded skill/CLI) so it can both post review
notes and consume the human's notes.
best practice — context:
building a bidirectional review surface; the demo does this with a
hunk-reviewskill that wrapshunk session commentsubcommands. Contingent on the tool exposing an agent-drivable interface to its comment store — read-only or human-only annotation stores do not qualify. - Manual "refresh to see new annotations" vs. live
--watchis an operator pacing choice, not just a preference. best practice — context: the reviewer controlling when new agent changes and notes appear; the source presenter prefers manual refresh (R) over--watchso updates land when he asks for them. Pacing over throughput — the same attention-budget logic firehose is built on, though the source frames it only as taste. - The demo exercises both directions on one surface: the agent flags a concurrency risk on a worker line, and a human note on a React line becomes an implemented reset button. observation — the concrete round-trip that distinguishes a shared surface from an ordinary diff viewer.
Related
- Agent Supervision — the operator workbench this refines: supervision makes agent output legible for accept/reject/annotate; a shared review surface adds the return path so the human's annotations become agent instructions.
- Agent-Computer Interface (ACI) — the shared diff-plus-skill is an ACI: the annotation store is the agent's tool, and how legibly it reads/writes comments gates how well the loop closes.
- CLI Tools over MCP Servers — the
surface is exposed as a skill wrapping CLI subcommands
(
hunk skill path,hunk session comment list) the agent drives via Bash. - Intent Context — a human note left on a line is captured intent, anchored to the code it refers to; the agent reads intent from the diff instead of from a detached prompt.
- Distillate: Hunk: the review diff as a two-way human↔︎agent annotation channel