Once the Chorus plugin is connected, it adds behavior around the workflow you already know
from [The AI-DLC workflow](/guides/ai-dlc-workflow/): it prompts for independent review at
the right moments, keeps agent sessions tracked without manual bookkeeping, and constrains
what an unattended agent may do. This page explains those behaviors. It does not repeat the
lifecycle stages or how to install, run, and recover a runtime — see
[The AI-DLC workflow](/guides/ai-dlc-workflow/),
[Operate the Chorus daemon](/guides/daemon-operations/),
[Interrupt and resume a session](/guides/session-recovery/), and the
[agent platforms reference](/reference/agents/) for those.

## Reviewer sub-agents

The plugin adds an independent quality gate at three points in the pipeline. At each point a
`PostToolUse` hook fires and injects a reminder that prompts the **main agent** to spawn a
dedicated **read-only reviewer sub-agent**. The reviewer is **not launched automatically** —
the main agent spawns it, waits using the runtime's completion mechanism, and reads the
current round's verdict comment. A completed review posts `PASS`, `PASS WITH NOTES`, or `FAIL`:

- `PASS` / `PASS WITH NOTES` — the work continues; notes are advisory.
- `FAIL` — the listed blockers must be fixed and the work re-submitted before it moves on.

Reviewers inspect the work rather than change it. The proposal reviewer may use read-only
shell commands such as `ls`, `rg`, `find`, and `git log/show/diff`, and must confirm a path is
missing before reporting it as a blocker. It must not modify files, perform Git write
operations, install dependencies, or run tests/builds. Task and code reviewers may also run
the project's own test, build, and lint commands, on every runtime including Kiro, where a
list of blocked commands stops file changes, Git writes, and installs.

| Reviewer | Fires after | Reviews | Verdict posted on |
| --- | --- | --- | --- |
| Proposal reviewer | `chorus_pm_submit_proposal` | Document completeness, task granularity, acceptance-criteria alignment, and the dependency graph | The proposal |
| Task reviewer | `chorus_submit_for_verify` | The task's implementation against its acceptance criteria and the proposal documents, plus default quality checks that apply even where no criterion speaks: correctness, reimplementing something that already exists, security holes in the task's own code, tests that could not fail, and failures of required operations that are silently swallowed | The task |
| Code reviewer | the last task of an idea-rooted proposal being verified (`chorus_admin_verify_task`) | The idea's **aggregate** change across all its tasks — cross-task integration, architecture drift, security, regressions, feature-level coverage | The idea |

The code reviewer is the final ship-time gate: it runs only when the *last* task of an
idea-rooted proposal is verified, and reviews the whole feature at once rather than a single
task.

### Follow findings across rounds

Every finding gets a stable ID: blockers are `B<round>-<slug>` and notes are
`N<round>-<slug>`, where the round is the one that first reported it — for example
`B1-ac3-not-implemented`. The ID never changes, so a `B1-…` line in a round-3 verdict tells
you that problem has survived two fix attempts. From round 2 on, the reviewer lists every
earlier finding under **Prior findings** with one of three states: `fixed`, `still-open`, or
`not-verifiable`, plus what it re-ran to decide. Only `fixed` closes a finding. A blocker that
is still open *or* could not be re-verified keeps the verdict at `FAIL`; an open note never
makes it worse than `PASS WITH NOTES`.

Verdicts have no length limit, so blocker evidence is written in full. To keep each comment
focused on what needs action, the first round reports at most five notes and later rounds add
no new notes.

### Wait for the current round's verdict

On Claude Code, wait for the reviewer's completion notification: the launch result is not
the verdict, even if a foreground launch was requested. On Codex, use its native spawn/wait
mechanism. Pi's bundled `subagent` tool blocks until the reviewer returns. In every case,
read the `VERDICT:` comment posted **after this dispatch**, not an older round's comment.

If there is no new verdict, distinguish silence from a deliberate handoff:

- **An explicit refusal or round-limit notice:** stop and hand the decision to a human.
  Do not respawn or replace the handoff with a self-reviewed verdict.
- **No response at all:** retry once. Check the retry for an explicit refusal too. Only if
  it is also silent may the main agent perform a read-only review and post its own verdict.
  No response is never a pass.

### Check alignment with the original intent

All three reviewers also compare the work with the originating Idea's intent: its body,
human-answered elaboration, and human-authored comments. Agent comments and agent-answered
elaboration are audit context, not authorization to change the scope.

Added scope, dropped requirements, or acceptance criteria that pass while missing the
original requirement are blockers unless a cited human comment, answer, or explicit human
override authorizes the change. The proposal reviewer checks the plan, the task reviewer
checks the implementation, and the code reviewer checks the whole feature.

### Turn reviewers on or off

The reviewers are gated by `userConfig` settings you can adjust when installing or
configuring the plugin. Each reviewer has an on/off toggle (all default **on**) and a
maximum-round limit that caps how many review-and-fix rounds run before the agent escalates
to a human instead of looping:

| Setting | Type | Default | Effect |
| --- | --- | --- | --- |
| `enableProposalReviewer` | boolean | `true` | Prompt to spawn the proposal reviewer after a proposal is submitted |
| `enableTaskReviewer` | boolean | `true` | Prompt to spawn the task reviewer after a task is submitted for verification |
| `enableCodeReviewer` | boolean | `true` | Prompt to spawn the code reviewer after the last task of an idea is verified |
| `maxProposalReviewRounds` | number | `3` | Maximum proposal review-and-fix rounds before escalating to a human (`0` = unlimited) |
| `maxTaskReviewRounds` | number | `3` | Maximum task review rounds before escalating (`0` = unlimited) |
| `maxCodeReviewRounds` | number | `3` | Maximum code-review rounds before escalating (`0` = unlimited) |

Turning a reviewer off saves tokens but removes its independent quality check. A
separate `enableOpenSpec` toggle governs OpenSpec mode, covered on its own page.

:::caution[Reviewer toggles exist only on Claude Code]
Both Claude Code and Codex ship all three reviewers and fire the same three review prompts.
What is Claude Code only is the `userConfig` **toggle surface** — the `enable*` switches and
the round-limit settings in the table above. Codex has no `userConfig`, so on Codex these
reviewers are governed by its skills and hooks directly rather than by install-time toggles.
See [What Codex does differently](#what-codex-does-differently) below. Do not read the
toggle difference as a difference in which reviewers exist.
:::

## Session lifecycle hooks

A second group of hooks manages the agent's Chorus **session** automatically, so neither you
nor the agent has to open, heartbeat, or close sessions by hand. These run on their own — no
judgment or prompting involved:

- **`SessionStart`** — checks connectivity, checks the agent in, and discovers any session
  the plugin pre-created for it.
- **`SubagentStart`** — before a worker starts, creates or reuses a Chorus session named for
  the worker's agent type. Workers of the same type can share it.
- **`SubagentStop`** — releases the exiting worker's hold on the session. Automatic task
  checkout, session closure, and eligible automatic verification wait until the last worker
  sharing that session exits.
- **Heartbeat and reminders** — an idle worker sends a heartbeat so its session is not
  marked inactive during long runs, and `PostToolUse` reminders nudge the main agent at the
  review points described above.

Because these hooks own the session lifecycle, an agent should never create or close a
session itself. For managing the runtime that these sessions run inside — starting it,
choosing working directories, interrupting, and resuming — see
[Operate the Chorus daemon](/guides/daemon-operations/) and
[Interrupt and resume a session](/guides/session-recovery/).

## Headless daemon sessions: no interactive prompts

When an agent runs unattended as a [daemon](/guides/daemon-operations/) session, there is no
human at a terminal to answer a pop-up. A headless session **must not** use interactive
prompts (such as `AskUserQuestion`) to reach a decision — a prompt no one can answer would
stall the run.

Instead, the agent routes every decision back **through Chorus**, where the responsible
human can respond asynchronously:

- Post an evidence-rich **comment** on the task or proposal and **@mention** the responsible
  human with the exact action the agent needs (for example, admin verification).
- Use **elaboration** to record open questions on an idea rather than blocking on a live
  answer.

This keeps the audit trail intact and lets the human respond when they are next in Chorus,
without the session waiting on a prompt it cannot surface. The same handoff applies whether
the session is interactive or headless; only the headless case makes the interactive prompt
impossible.

## What Codex does differently

The Codex plugin is a port, not a mirror. It runs the **same three reviewers** as Claude
Code — proposal, task, and code — each prompted by the same `PostToolUse` / hook nudge after
a proposal is submitted, a task is submitted for verification, and the last task of an
idea-rooted proposal is verified. Where it differs is the configuration and spawning
mechanics, not the set of reviewers:

- **No `userConfig` toggle surface.** Codex exposes no `enable*` reviewer switches and no
  round-limit settings. The reviewer prompts are driven by Codex's skills and hooks
  directly, so they cannot be turned off at install time the way they can on Claude Code —
  the code-review prompt, for instance, defaults on and has no toggle to disable it.
- **Native spawning.** The main agent invokes a reviewer through Codex's own
  `spawn_agent` / `wait_agent` rather than Claude Code's Agent Teams, and there are no
  Codex equivalents for the `TeammateIdle` and `TaskCompleted` hooks.

Automation differs on the OpenClaw, Kiro, and Pi runtimes. Rather than assuming the Claude
Code behavior, check each runtime's page under the
[agent platforms reference](/reference/agents/) for what it supports.

## For agents

- **Triggers:**
  - After `chorus_pm_submit_proposal`, a `PostToolUse` hook prompts you to spawn
    `chorus:proposal-reviewer`; wait for completion, then read this round's `VERDICT:`
    comment on the proposal.
  - After `chorus_submit_for_verify`, spawn `chorus:task-reviewer`; read its `VERDICT:`
    comment on the task.
  - After `chorus_admin_verify_task` on the **last** task of an idea-rooted proposal, spawn
    the code reviewer; read its `VERDICT:` comment on the idea. This runs on both Claude Code
    (`chorus:code-reviewer`) and Codex (`chorus-code-reviewer`).
  - Reviewers are **not** auto-launched — you spawn them yourself and wait for the verdict.
    `PASS` / `PASS WITH NOTES` continue; `FAIL` means fix the blockers and re-submit.
- **Constraints:**
  - Follow the read-only limits and current-round waiting rules above. Proposal review
    permits shell inspection, not tests/builds. Never bypass an explicit human escalation
    by respawning or self-reviewing.
  - All three reviewers (proposal, task, code) ship on **both** Claude Code and Codex. Only
    the `userConfig` toggle surface is Claude Code only — the `enable*` switches
    (`enableProposalReviewer`, `enableTaskReviewer`, `enableCodeReviewer`) and the round
    limits (`maxProposalReviewRounds`, `maxTaskReviewRounds`, `maxCodeReviewRounds`,
    default 3, `0` = unlimited). Codex has no `userConfig`, so on Codex the reviewers are
    governed by its skills and hooks directly and cannot be toggled off at install time.
  - Do **not** call `chorus_create_session` or `chorus_close_session` — the session
    lifecycle hooks (`SessionStart`, `SubagentStart`, `SubagentStop`) manage it.
  - A **headless** daemon session must **not** use interactive prompts (`AskUserQuestion`
    and similar). Route decisions through Chorus comments + `@mention` and elaboration.