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.

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 run read-only and test/build commands where their runtime permits; Kiro’s task and code reviewers have no shell access.

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	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. The three matchers that trigger these prompts live in public/chorus-plugin/hooks/hooks.json.

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. This is a review skill rule using existing Idea, elaboration, and comment reads, not a new MCP tool.

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 removes its independent quality check but reduces token usage. A separate enableOpenSpec toggle governs OpenSpec mode, covered on its own page.

Only the toggle surface is Claude Code only

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 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 — creates or reuses a Chorus session named for the worker’s agent type before it starts. Same-type workers can share it.
• SubagentStop — releases the exiting worker’s hold. 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 you need (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 gateway, 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.

For the OpenClaw, Kiro, and Pi runtimes, treat automation as a difference-and-pointer: see each runtime’s page under the agent platforms reference for what it supports rather than assuming the Claude Code behavior.

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.
• Cite:
  • Hook events and PostToolUse matchers: public/chorus-plugin/hooks/hooks.json.
  • Reviewer roles: public/chorus-plugin/agents/proposal-reviewer.md, public/chorus-plugin/agents/task-reviewer.md, public/chorus-plugin/agents/code-reviewer.md.
  • userConfig toggles and round limits (Claude Code only): public/chorus-plugin/.claude-plugin/plugin.json.
  • Codex ships the same three reviewers with no userConfig surface: plugins/chorus/skills/chorus-code-reviewer/SKILL.md, plugins/chorus/hooks/on-post-verify-task.sh (the code-review gateway nudge), and plugins/chorus/.codex-plugin/plugin.json.
  • Hook-and-skill division: docs/chorus-plugin.md.
  • Headless interaction guard: docs/DAEMON.md and the develop / quick-dev skills.