Automation behaviors

Once the Chorus plugin is connected, it adds behavior around the workflow you already know from The 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, Operate the Chorus daemon, Interrupt and resume a session, and the agent platforms reference for those.

Hermes automation

Hermes injects session check-in and spec context through native hooks and appends review reminders after proposal submission, task submission, and final task verification. The main agent invokes delegate_task with a [chorus-reviewer:proposal], [chorus-reviewer:task], or [chorus-reviewer:code] marker and loads the matching skill. Marked children may read and post verdicts but cannot execute terminal commands, edit files, or delegate further. Gateway command approvals go to the owner through Chorus comments; use approvals.mode manual and security.approval.transport chorus. Interactive sessions use the configured builtin fallback. This is distinct from the Claude daemon headless guard below.

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.

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 and Interrupt and resume a session.

Headless daemon sessions: no interactive prompts

When an agent runs unattended as a daemon 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 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.