supipowers 1.5.3 → 2.0.0

package/src/review/agent-loader.ts

@@ -11,12 +11,18 @@ import type {
   ReviewAgentDefinition,
   ReviewAgentsConfig,
 } from "../types.js";
-import { normalizeLineEndings } from "../text.js";
+import { parseMarkdownFrontmatter } from "../markdown-frontmatter.js";
+import { resolvePackageManager } from "../workspace/package-manager.js";
+import { resolveRepoRootFromFs } from "../workspace/repo-root.js";
+import {
+  getRootStateDir,
+  getWorkspaceStateDir,
+} from "../workspace/state-paths.js";
+import { discoverWorkspaceTargets } from "../workspace/targets.js";
+import { collectValidationErrors, formatValidationErrors } from "../ai/structured-output.js";
 import {
   ReviewAgentFrontmatterSchema,
   ReviewAgentsConfigSchema,
-  collectReviewValidationErrors,
-  formatReviewValidationErrors,
 } from "./types.js";
 
 const REVIEW_AGENTS_DIR = "review-agents";
@@ -41,6 +47,16 @@ export interface LoadedReviewAgents {
   agents: ConfiguredReviewAgent[];
 }
 
+export interface ReviewAgentLoadOptions {
+  repoRoot?: string;
+  workspaceRelativeDir?: string | null;
+}
+
+export interface ResolvedReviewAgentContext {
+  repoRoot: string;
+  workspaceRelativeDir: string | null;
+}
+
 const CONFIG_HEADER = [
   "# Review Agents Configuration",
   "#",
@@ -50,6 +66,7 @@ const CONFIG_HEADER = [
   "#   data:          string   - markdown file name in the agents directory",
   "#   model:         string   - model id (e.g. \"anthropic/claude-sonnet-4-20250514\") or null to inherit",
   "#   thinkingLevel: string   - off | minimal | low | medium | high | xhigh | null to inherit",
+  "#   peerCoordination: boolean  - opt this agent into IRC peer coordination (multi-agent reviews only); omit or set false to disable",
   "#",
 ].join("\n");
 
@@ -65,6 +82,7 @@ function serializeConfigYaml(agents: ReviewAgentConfig[]): string {
       `    data: ${a.data}`,
       `    model: ${a.model ?? "null"}`,
       `    thinkingLevel: ${a.thinkingLevel ?? "null"}`,
+      ...(a.peerCoordination === true ? [`    peerCoordination: true`] : []),
     ]),
     "",
   ].join("\n");
@@ -113,6 +131,13 @@ function migrateConfigIfNeeded(configPath: string): void {
     } else if (current && trimmed.startsWith("thinkingLevel:")) {
       const val = trimmed.slice("thinkingLevel:".length).trim();
       current.thinkingLevel = val === "null" ? null : (val as any);
+    } else if (current && trimmed.startsWith("peerCoordination:")) {
+      const val = trimmed.slice("peerCoordination:".length).trim();
+      if (val === "true") {
+        current.peerCoordination = true;
+      } else if (val === "false") {
+        current.peerCoordination = false;
+      }
     }
   }
   if (current?.name) agents.push(current as ReviewAgentConfig);
@@ -128,7 +153,7 @@ function migrateConfigIfNeeded(configPath: string): void {
 }
 
 function validateReviewAgentsConfig(data: unknown): ReviewAgentsConfig {
-  const errors = formatReviewValidationErrors(collectReviewValidationErrors(ReviewAgentsConfigSchema, data));
+  const errors = formatValidationErrors(collectValidationErrors(ReviewAgentsConfigSchema, data));
   if (errors.length > 0) {
     throw new Error(`Invalid review-agents config: ${errors.join("; ")}`);
   }
@@ -142,57 +167,27 @@ async function importYamlFile(filePath: string): Promise<unknown> {
   return imported.default;
 }
 
-function parseFrontmatter(frontmatter: string, filePath: string): ReviewAgentDefinition {
-  const metadata: Record<string, unknown> = {};
-
-  for (const line of frontmatter.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) {
-      continue;
-    }
-
-    const separator = trimmed.indexOf(":");
-    if (separator === -1) {
-      continue;
-    }
-
-    const key = trimmed.slice(0, separator).trim();
-    const value = trimmed.slice(separator + 1).trim();
-    metadata[key] = value;
-  }
-
-  const errors = formatReviewValidationErrors(
-    collectReviewValidationErrors(ReviewAgentFrontmatterSchema, metadata),
+export function parseReviewAgentMarkdown(content: string, filePath: string): ReviewAgentDefinition {
+  const { frontmatter, body } = parseMarkdownFrontmatter(content, filePath);
+  const errors = formatValidationErrors(
+    collectValidationErrors(ReviewAgentFrontmatterSchema, frontmatter),
   );
   if (errors.length > 0) {
     throw new Error(`Invalid agent frontmatter in ${filePath}: ${errors.join("; ")}`);
   }
 
-  return {
-    name: String(metadata.name),
-    description: String(metadata.description),
-    focus: typeof metadata.focus === "string" ? metadata.focus : null,
-    prompt: "",
-    filePath,
+  const parsed = frontmatter as {
+    name: string;
+    description: string;
+    focus?: string;
   };
-}
-
-export function parseReviewAgentMarkdown(content: string, filePath: string): ReviewAgentDefinition {
-  const normalized = normalizeLineEndings(content);
-  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!match) {
-    throw new Error(`Review agent file ${filePath} is missing YAML frontmatter.`);
-  }
-
-  const definition = parseFrontmatter(match[1], filePath);
-  const prompt = match[2]?.trim();
-  if (!prompt) {
-    throw new Error(`Review agent file ${filePath} has an empty prompt body.`);
-  }
 
   return {
-    ...definition,
-    prompt,
+    name: parsed.name,
+    description: parsed.description,
+    focus: parsed.focus ?? null,
+    prompt: body,
+    filePath,
   };
 }
 
@@ -204,37 +199,71 @@ export function getReviewAgentsConfigPath(paths: PlatformPaths, cwd: string): st
   return path.join(getReviewAgentsDir(paths, cwd), CONFIG_FILE);
 }
 
-export function ensureDefaultReviewAgents(paths: PlatformPaths, cwd: string): void {
-  const agentsDir = getReviewAgentsDir(paths, cwd);
-  fs.mkdirSync(agentsDir, { recursive: true });
+export function getRootReviewAgentsDir(paths: PlatformPaths, repoRoot: string): string {
+  return path.join(getRootStateDir(paths, repoRoot), REVIEW_AGENTS_DIR);
+}
 
-  // Default agent markdown files are installed globally only.
-  writeIfMissing(getReviewAgentsConfigPath(paths, cwd), buildDefaultConfigText());
-  migrateConfigIfNeeded(getReviewAgentsConfigPath(paths, cwd));
+export function getRootReviewAgentsConfigPath(paths: PlatformPaths, repoRoot: string): string {
+  return path.join(getRootReviewAgentsDir(paths, repoRoot), CONFIG_FILE);
 }
 
-export async function loadReviewAgentsConfig(paths: PlatformPaths, cwd: string): Promise<ReviewAgentsConfig> {
-  ensureGlobalDefaultReviewAgents(paths);
-  ensureDefaultReviewAgents(paths, cwd);
-  return validateReviewAgentsConfig(await importYamlFile(getReviewAgentsConfigPath(paths, cwd)));
+export function getWorkspaceReviewAgentsDir(
+  paths: PlatformPaths,
+  repoRoot: string,
+  workspaceRelativeDir: string,
+): string {
+  return path.join(getWorkspaceStateDir(paths, repoRoot, workspaceRelativeDir), REVIEW_AGENTS_DIR);
 }
 
-export async function loadReviewAgents(paths: PlatformPaths, cwd: string): Promise<LoadedReviewAgents> {
-  const agentsDir = getReviewAgentsDir(paths, cwd);
-  const configPath = getReviewAgentsConfigPath(paths, cwd);
-  const globalAgentsDir = getGlobalReviewAgentsDir(paths);
-  const config = await loadReviewAgentsConfig(paths, cwd);
+export function getWorkspaceReviewAgentsConfigPath(
+  paths: PlatformPaths,
+  repoRoot: string,
+  workspaceRelativeDir: string,
+): string {
+  return path.join(getWorkspaceReviewAgentsDir(paths, repoRoot, workspaceRelativeDir), CONFIG_FILE);
+}
+
+
+export function resolveReviewAgentContext(
+  cwd: string,
+  options?: ReviewAgentLoadOptions,
+): ResolvedReviewAgentContext {
+  const repoRoot = options?.repoRoot ?? resolveRepoRootFromFs(cwd);
+  const explicitWorkspaceRelativeDir = options?.workspaceRelativeDir;
+  if (explicitWorkspaceRelativeDir !== undefined) {
+    return {
+      repoRoot,
+      workspaceRelativeDir: explicitWorkspaceRelativeDir && explicitWorkspaceRelativeDir !== "."
+        ? explicitWorkspaceRelativeDir
+        : null,
+    };
+  }
+
+  const packageManager = resolvePackageManager(repoRoot);
+  const workspaceTarget = discoverWorkspaceTargets(repoRoot, packageManager.id)
+    .filter((target) => cwd === target.packageDir || cwd.startsWith(`${target.packageDir}${path.sep}`))
+    .sort((left, right) => right.packageDir.length - left.packageDir.length)[0];
 
-  const agents = config.agents
+  return {
+    repoRoot,
+    workspaceRelativeDir: workspaceTarget?.kind === "workspace" ? workspaceTarget.relativeDir : null,
+  };
+}
+
+function loadAgentsFromConfig(
+  config: ReviewAgentsConfig,
+  lookupDirs: string[],
+  missingScopeLabel: string,
+  scope?: ConfiguredReviewAgent["scope"],
+): ConfiguredReviewAgent[] {
+  return config.agents
     .filter((agent) => agent.enabled)
     .map((agent) => {
-      const projectFilePath = path.join(agentsDir, agent.data);
-      const globalFilePath = path.join(globalAgentsDir, agent.data);
-      const filePath = fs.existsSync(projectFilePath) ? projectFilePath : globalFilePath;
-      if (!fs.existsSync(filePath)) {
-        throw new Error(
-          `Configured review agent file does not exist in project or global scope: ${agent.data}`
-        );
+      const filePath = lookupDirs
+        .map((dir) => path.join(dir, agent.data))
+        .find((candidatePath) => fs.existsSync(candidatePath));
+      if (!filePath) {
+        throw new Error(`Configured review agent file does not exist in ${missingScopeLabel}: ${agent.data}`);
       }
 
       const definition = parseReviewAgentMarkdown(fs.readFileSync(filePath, "utf-8"), filePath);
@@ -250,8 +279,55 @@ export async function loadReviewAgents(paths: PlatformPaths, cwd: string): Promi
         data: agent.data,
         model: agent.model,
         thinkingLevel: agent.thinkingLevel ?? null,
+        ...(agent.peerCoordination === true ? { peerCoordination: true } : {}),
+        ...(scope ? { scope } : {}),
       } satisfies ConfiguredReviewAgent;
     });
+}
+
+function mergeAgentLayers(
+  lowerAgents: ConfiguredReviewAgent[],
+  higherAgents: ConfiguredReviewAgent[],
+  higherConfig: ReviewAgentsConfig,
+): ConfiguredReviewAgent[] {
+  const higherConfigNames = new Set(higherConfig.agents.map((agent) => agent.name));
+  return [
+    ...lowerAgents.filter((agent) => !higherConfigNames.has(agent.name)),
+    ...higherAgents,
+  ];
+}
+
+export function ensureDefaultReviewAgents(paths: PlatformPaths, cwd: string): void {
+  const agentsDir = getReviewAgentsDir(paths, cwd);
+  fs.mkdirSync(agentsDir, { recursive: true });
+
+  // Default agent markdown files are installed globally only.
+  writeIfMissing(getReviewAgentsConfigPath(paths, cwd), buildDefaultConfigText());
+  migrateConfigIfNeeded(getReviewAgentsConfigPath(paths, cwd));
+}
+
+export async function loadReviewAgentsConfig(
+  paths: PlatformPaths,
+  cwd: string,
+  options?: ReviewAgentLoadOptions,
+): Promise<ReviewAgentsConfig> {
+  const context = resolveReviewAgentContext(cwd, options);
+  ensureGlobalDefaultReviewAgents(paths);
+  ensureDefaultReviewAgents(paths, context.repoRoot);
+  return validateReviewAgentsConfig(await importYamlFile(getRootReviewAgentsConfigPath(paths, context.repoRoot)));
+}
+
+export async function loadReviewAgents(
+  paths: PlatformPaths,
+  cwd: string,
+  options?: ReviewAgentLoadOptions,
+): Promise<LoadedReviewAgents> {
+  const context = resolveReviewAgentContext(cwd, options);
+  const agentsDir = getRootReviewAgentsDir(paths, context.repoRoot);
+  const configPath = getRootReviewAgentsConfigPath(paths, context.repoRoot);
+  const globalAgentsDir = getGlobalReviewAgentsDir(paths);
+  const config = await loadReviewAgentsConfig(paths, cwd, context);
+  const agents = loadAgentsFromConfig(config, [agentsDir, globalAgentsDir], "root or global scope");
 
   return {
     agentsDir,
@@ -292,31 +368,64 @@ export async function loadGlobalReviewAgents(paths: PlatformPaths): Promise<Load
   const agentsDir = getGlobalReviewAgentsDir(paths);
   const configPath = getGlobalReviewAgentsConfigPath(paths);
   const config = await loadGlobalReviewAgentsConfig(paths);
+  const agents = loadAgentsFromConfig(config, [agentsDir], "global scope", "global");
 
-  const agents = config.agents
-    .filter((agent) => agent.enabled)
-    .map((agent) => {
-      const filePath = path.join(agentsDir, agent.data);
-      if (!fs.existsSync(filePath)) {
-        throw new Error(`Configured review agent file does not exist: ${filePath}`);
-      }
+  return {
+    agentsDir,
+    configPath,
+    config,
+    agents,
+  };
+}
 
-      const definition = parseReviewAgentMarkdown(fs.readFileSync(filePath, "utf-8"), filePath);
-      if (definition.name !== agent.name) {
-        throw new Error(
-          `Configured agent name "${agent.name}" does not match frontmatter name "${definition.name}" in ${filePath}.`,
-        );
-      }
+async function loadWorkspaceReviewAgentsConfig(
+  paths: PlatformPaths,
+  cwd: string,
+  options: ReviewAgentLoadOptions,
+): Promise<ReviewAgentsConfig> {
+  const context = resolveReviewAgentContext(cwd, options);
+  if (!context.workspaceRelativeDir) {
+    return { agents: [] };
+  }
 
-      return {
-        ...definition,
-        enabled: agent.enabled,
-        data: agent.data,
-        model: agent.model,
-        thinkingLevel: agent.thinkingLevel ?? null,
-        scope: "global" as const,
-      } satisfies ConfiguredReviewAgent;
-    });
+  const configPath = getWorkspaceReviewAgentsConfigPath(
+    paths,
+    context.repoRoot,
+    context.workspaceRelativeDir,
+  );
+  if (!fs.existsSync(configPath)) {
+    return { agents: [] };
+  }
+
+  migrateConfigIfNeeded(configPath);
+  return validateReviewAgentsConfig(await importYamlFile(configPath));
+}
+
+async function loadWorkspaceReviewAgents(
+  paths: PlatformPaths,
+  cwd: string,
+  options: ReviewAgentLoadOptions,
+): Promise<LoadedReviewAgents | null> {
+  const context = resolveReviewAgentContext(cwd, options);
+  if (!context.workspaceRelativeDir) {
+    return null;
+  }
+
+  const agentsDir = getWorkspaceReviewAgentsDir(paths, context.repoRoot, context.workspaceRelativeDir);
+  const configPath = getWorkspaceReviewAgentsConfigPath(
+    paths,
+    context.repoRoot,
+    context.workspaceRelativeDir,
+  );
+  const rootAgentsDir = getRootReviewAgentsDir(paths, context.repoRoot);
+  const globalAgentsDir = getGlobalReviewAgentsDir(paths);
+  const config = await loadWorkspaceReviewAgentsConfig(paths, cwd, context);
+  const agents = loadAgentsFromConfig(
+    config,
+    [agentsDir, rootAgentsDir, globalAgentsDir],
+    "workspace, root, or global scope",
+    "workspace",
+  );
 
   return {
     agentsDir,
@@ -326,31 +435,34 @@ export async function loadGlobalReviewAgents(paths: PlatformPaths): Promise<Load
   };
 }
 
-// ── Merged Loading (Global + Project) ──────────────────────
+// ── Merged Loading (Global + Root + Workspace) ───────────────
 
 export async function loadMergedReviewAgents(
   paths: PlatformPaths,
   cwd: string,
+  options?: ReviewAgentLoadOptions,
 ): Promise<LoadedReviewAgents> {
+  const context = resolveReviewAgentContext(cwd, options);
   const globalResult = await loadGlobalReviewAgents(paths);
-  const projectResult = await loadReviewAgents(paths, cwd);
-
-  // Project config is authoritative: any agent named in the project config
-  // (enabled or disabled) shadows the global version with the same name.
-  const projectConfigNames = new Set(projectResult.config.agents.map((a) => a.name));
-  const uniqueGlobalAgents = globalResult.agents.filter((a) => !projectConfigNames.has(a.name));
-
-  // Tag project agents with scope
-  const projectAgents = projectResult.agents.map((agent) => ({
-    ...agent,
-    scope: "project" as const,
-  }));
+  const rootResult = await loadReviewAgents(paths, cwd, context);
+  const rootAgents = rootResult.agents.map((agent) => ({ ...agent, scope: "root" as const }));
+  const mergedRootAgents = mergeAgentLayers(globalResult.agents, rootAgents, rootResult.config);
+
+  const workspaceResult = await loadWorkspaceReviewAgents(paths, cwd, context);
+  if (!workspaceResult) {
+    return {
+      agentsDir: rootResult.agentsDir,
+      configPath: rootResult.configPath,
+      config: rootResult.config,
+      agents: mergedRootAgents,
+    };
+  }
 
   return {
-    agentsDir: projectResult.agentsDir,
-    configPath: projectResult.configPath,
-    config: projectResult.config,
-    agents: [...uniqueGlobalAgents, ...projectAgents],
+    agentsDir: workspaceResult.agentsDir,
+    configPath: workspaceResult.configPath,
+    config: workspaceResult.config,
+    agents: mergeAgentLayers(mergedRootAgents, workspaceResult.agents, workspaceResult.config),
   };
 }
 

package/src/review/fixer.ts

@@ -1,5 +1,4 @@
 import fixFindingsPrompt from "./prompts/fix-findings.md" with { type: "text" };
-import fixOutputSchemaPrompt from "./prompts/fix-output-schema.md" with { type: "text" };
 import type {
   GateExecutionContext,
   ReviewFinding,
@@ -8,9 +7,12 @@ import type {
   ReviewOutput,
   ReviewScope,
 } from "../types.js";
-import { parseStructuredOutput, runWithOutputValidation } from "./output.js";
+import { parseStructuredOutput, runWithOutputValidation, type ReliabilityReporter } from "../ai/structured-output.js";
+import { renderSchemaText } from "../ai/schema-text.js";
 import { ReviewFixOutputSchema } from "./types.js";
-import { renderReviewTemplate } from "./template.js";
+import { renderTemplate } from "../ai/template.js";
+
+const REVIEW_FIX_OUTPUT_SCHEMA_TEXT = renderSchemaText(ReviewFixOutputSchema);
 
 export interface ReviewFixInput {
   cwd: string;
@@ -20,6 +22,7 @@ export interface ReviewFixInput {
   model?: string;
   thinkingLevel?: string | null;
   timeoutMs?: number;
+  reliability?: ReliabilityReporter;
 }
 
 export interface ReviewFixRunResult {
@@ -127,10 +130,10 @@ function normalizeFixOutput(
 }
 
 export function buildFixPrompt(scope: ReviewScope, findings: ReviewFinding[]): string {
-  return renderReviewTemplate(fixFindingsPrompt, {
+  return renderTemplate(fixFindingsPrompt, {
     scope,
     findingsJson: JSON.stringify(findings, null, 2),
-    fixOutputSchema: fixOutputSchemaPrompt.trim(),
+    fixOutputSchema: REVIEW_FIX_OUTPUT_SCHEMA_TEXT,
   });
 }
 
@@ -158,13 +161,14 @@ export async function runAutoFix(input: ReviewFixInput): Promise<ReviewFixRunRes
   const result = await runWithOutputValidation(input.createAgentSession, {
     cwd: input.cwd,
     prompt: buildFixPrompt(input.scope, fixableFindings),
-    schema: fixOutputSchemaPrompt.trim(),
+    schema: REVIEW_FIX_OUTPUT_SCHEMA_TEXT,
     parse(raw) {
       return parseStructuredOutput<ReviewFixOutput>(raw, ReviewFixOutputSchema);
     },
     model: input.model,
     thinkingLevel: input.thinkingLevel ?? null,
     timeoutMs: input.timeoutMs ?? 180_000,
+    reliability: input.reliability,
   });
 
   if (result.status === "blocked") {

package/src/review/multi-agent-runner.ts

@@ -1,9 +1,13 @@
 import agentReviewWrapperPrompt from "./prompts/agent-review-wrapper.md" with { type: "text" };
 import outputInstructionsPrompt from "./prompts/output-instructions.md" with { type: "text" };
-import reviewOutputSchema from "./prompts/review-output-schema.md" with { type: "text" };
 import type { ConfiguredReviewAgent, GateExecutionContext, ReviewOutput, ReviewScope } from "../types.js";
-import { explainReviewOutputFailure, parseReviewOutput, runWithOutputValidation } from "./output.js";
-import { renderReviewTemplate } from "./template.js";
+import { runWithOutputValidation, type ReliabilityReporter } from "../ai/structured-output.js";
+import { renderSchemaText } from "../ai/schema-text.js";
+import { explainReviewOutputFailure, parseReviewOutput } from "./output.js";
+import { renderTemplate } from "../ai/template.js";
+import { ReviewOutputSchema } from "./types.js";
+
+const REVIEW_OUTPUT_SCHEMA_TEXT = renderSchemaText(ReviewOutputSchema);
 
 export interface MultiAgentReviewInput {
   cwd: string;
@@ -13,8 +17,11 @@ export interface MultiAgentReviewInput {
   model?: string;
   thinkingLevel?: string | null;
   timeoutMs?: number;
+  /** Tool ids active in the host runtime. Used to gate `peerCoordination` on `irc`. */
+  activeTools?: string[];
   onAgentStart?: (agent: ConfiguredReviewAgent) => void;
   onAgentComplete?: (result: MultiAgentAgentResult) => void;
+  reliability?: ReliabilityReporter;
 }
 
 export interface MultiAgentAgentResult {
@@ -30,8 +37,8 @@ export interface MultiAgentReviewResult {
 }
 
 function renderOutputInstructions(): string {
-  return renderReviewTemplate(outputInstructionsPrompt, {
-    outputSchema: reviewOutputSchema.trim(),
+  return renderTemplate(outputInstructionsPrompt, {
+    outputSchema: REVIEW_OUTPUT_SCHEMA_TEXT,
   });
 }
 
@@ -41,18 +48,95 @@ export function buildConfiguredAgentPrompt(agent: ConfiguredReviewAgent, scope:
   }
 
   const outputInstructions = renderOutputInstructions();
-  const agentPrompt = renderReviewTemplate(
-    agent.prompt.replaceAll("{output_instructions}", "{{outputInstructions}}"),
-    { outputInstructions },
-  );
+  const agentPrompt = renderTemplate(agent.prompt.replaceAll("{output_instructions}", "{{outputInstructions}}"),
+  { outputInstructions },);
 
-  return renderReviewTemplate(agentReviewWrapperPrompt, {
+  return renderTemplate(agentReviewWrapperPrompt, {
     agent,
     agentPrompt,
     scope,
   });
 }
 
+interface PeerCoordinationIdentity {
+  agent: ConfiguredReviewAgent;
+  id: string;
+  displayName: string;
+}
+
+const PEER_COORDINATION_AGENT_ID_PREFIX = "supi-review";
+
+function normalizePeerCoordinationIdSegment(name: string, fallbackIndex: number): string {
+  const normalized = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || `agent-${fallbackIndex + 1}`;
+}
+
+function normalizePeerCoordinationDisplayName(name: string, fallbackIndex: number): string {
+  const normalized = name.trim().replace(/\s+/g, " ");
+  return normalized || `review-agent-${fallbackIndex + 1}`;
+}
+
+export function buildPeerCoordinationIdentities(
+  agents: ConfiguredReviewAgent[],
+): PeerCoordinationIdentity[] {
+  const countsByBaseId = new Map<string, number>();
+  return agents.map((agent, index) => {
+    const segment = normalizePeerCoordinationIdSegment(agent.name, index);
+    const baseId = `${PEER_COORDINATION_AGENT_ID_PREFIX}-${segment}`;
+    const previousCount = countsByBaseId.get(baseId) ?? 0;
+    countsByBaseId.set(baseId, previousCount + 1);
+    return {
+      agent,
+      id: previousCount === 0 ? baseId : `${baseId}-${previousCount + 1}`,
+      displayName: normalizePeerCoordinationDisplayName(agent.name, index),
+    };
+  });
+}
+
+/**
+ * Build the IRC peer-coordination prompt block for one agent.
+ *
+ * Returns `null` when peer coordination is disabled, the host runtime does not
+ * expose the `irc` tool, or the agent has no peers (single-agent run, or only
+ * itself opted in).
+ */
+export function buildPeerCoordinationPromptBlock(
+  agent: ConfiguredReviewAgent,
+  peers: ConfiguredReviewAgent[],
+  activeTools: string[],
+  identities: PeerCoordinationIdentity[] = buildPeerCoordinationIdentities(peers),
+): string | null {
+  if (agent.peerCoordination !== true) return null;
+  if (!activeTools.includes("irc")) return null;
+
+  const self = identities.find((identity) => identity.agent === agent);
+  if (!self) return null;
+
+  const otherPeers = identities.filter(
+    (identity) => identity.agent.peerCoordination === true && identity.agent !== agent,
+  );
+  if (otherPeers.length === 0) return null;
+
+  return [
+    "## IRC peer coordination",
+    "",
+    `You are running as \`${self.id}\` in a multi-agent review. Other reviewers also opted into peer coordination:`,
+    ...otherPeers.map((peer) => `- \`${peer.id}\` — ${peer.displayName}`),
+    "",
+    "Use the OMP `irc` tool when continuing alone is wasteful or wrong:",
+    "- Send a DM with `irc({ op: \"send\", to: \"<peer-id>\", message: \"...\" })` when you spot work a peer is already filing, when you need their finding for context, or when you would otherwise duplicate analysis.",
+    "- Reply in plain prose. Do **NOT** send JSON status payloads. Do **NOT** quote the message you are replying to.",
+    "- One DM is one round-trip. Do **NOT** follow up with \"did you get my message?\".",
+    "- Use exactly the peer ids listed above. Do **NOT** invent ids from agent names, and do **NOT** broadcast unless you genuinely need every peer.",
+    "- If a peer has already filed an equivalent finding, do **NOT** file a duplicate; defer to theirs.",
+    "",
+  ].join("\n");
+}
+
 function aggregateAgentOutputs(results: MultiAgentAgentResult[]): ReviewOutput {
   const findings = results.flatMap((result) =>
     result.output.findings.map((finding) => ({
@@ -73,13 +157,25 @@ function aggregateAgentOutputs(results: MultiAgentAgentResult[]): ReviewOutput {
 async function runConfiguredAgent(
   input: Omit<MultiAgentReviewInput, "agents">,
   agent: ConfiguredReviewAgent,
+  peers: ConfiguredReviewAgent[],
+  peerIdentities: PeerCoordinationIdentity[],
 ): Promise<MultiAgentAgentResult> {
   input.onAgentStart?.(agent);
 
+  const identity = peerIdentities.find((peer) => peer.agent === agent);
+  const basePrompt = buildConfiguredAgentPrompt(agent, input.scope);
+  const peerBlock = buildPeerCoordinationPromptBlock(
+    agent,
+    peers,
+    input.activeTools ?? [],
+    peerIdentities,
+  );
+  const prompt = peerBlock ? `${peerBlock}\n${basePrompt}` : basePrompt;
+
   const result = await runWithOutputValidation(input.createAgentSession, {
     cwd: input.cwd,
-    prompt: buildConfiguredAgentPrompt(agent, input.scope),
-    schema: reviewOutputSchema.trim(),
+    prompt,
+    schema: REVIEW_OUTPUT_SCHEMA_TEXT,
     parse(raw) {
       const output = parseReviewOutput(raw);
       return {
@@ -89,7 +185,11 @@ async function runConfiguredAgent(
     },
     model: agent.model ?? input.model,
     thinkingLevel: agent.thinkingLevel ?? input.thinkingLevel ?? null,
+    ...(peerBlock && identity
+      ? { agentId: identity.id, agentDisplayName: identity.displayName }
+      : {}),
     timeoutMs: input.timeoutMs ?? 120_000,
+    reliability: input.reliability,
   });
 
   if (result.status === "blocked") {
@@ -124,8 +224,9 @@ async function runConfiguredAgent(
 }
 
 export async function runMultiAgentReview(input: MultiAgentReviewInput): Promise<MultiAgentReviewResult> {
+  const peerIdentities = buildPeerCoordinationIdentities(input.agents);
   const results = await Promise.all(
-    input.agents.map((agent) => runConfiguredAgent(input, agent)),
+    input.agents.map((agent) => runConfiguredAgent(input, agent, input.agents, peerIdentities)),
   );
 
   return {