aiwcli 0.11.0 → 0.12.0

package/dist/templates/cc-native/_cc-native/hooks/cc-native-plan-review.ts

@@ -35,14 +35,17 @@ import {
   emitContext,
   emitContextAndBlock,
 } from "../../_shared/lib-ts/base/hook-utils.js";
-import { isInternalCall } from "../../_shared/lib-ts/base/subprocess-utils.js";
+import { isInternalCall, findExecutable } from "../../_shared/lib-ts/base/subprocess-utils.js";
 import { getProjectRoot, getAiwcliDir, getContextReviewsDir, getContextDir, getReviewFolderPath } from "../../_shared/lib-ts/base/constants.js";
 import { eprint } from "../../_shared/lib-ts/base/utils.js";
 import { getContextBySessionId, getAllContexts } from "../../_shared/lib-ts/context/context-store.js";
+import { findPlanPathInTranscript } from "../../_shared/lib-ts/context/plan-manager.js";
 
 import type {
   AgentConfig,
   OrchestratorConfig,
+  ProviderConfig,
+  ModelsConfig,
   ReviewerResult,
   CombinedReviewResult,
   OrchestratorResult,
@@ -59,10 +62,14 @@ import {
 import {
   isPlanAlreadyReviewed,
   wasPlanPreviouslyDenied,
+  getLastPlanReview,
   markPlanReviewed,
+  wasQuestionsAsked,
+  markQuestionsAsked,
 } from "../lib-ts/cc-native-state.js";
 
-import { worstVerdict, computeReviewDecision } from "../lib-ts/verdict.js";
+import { worstVerdict } from "../lib-ts/verdict.js";
+import { computeCorroboratedDecision } from "../lib-ts/corroboration.js";
 import { loadConfig, getDisplaySettings } from "../lib-ts/config.js";
 import { runOrchestrator } from "../lib-ts/orchestrator.js";
 import { aggregateAgents } from "../lib-ts/aggregate-agents.js";
@@ -72,10 +79,13 @@ import {
   buildInlineReviewSummary,
   extractTopIssuesText,
   buildHighIssuesDocument,
+  buildCorroborationReport,
   writeReviewTracker,
 } from "../lib-ts/artifacts.js";
 import type { ReviewTrackerEntry } from "../lib-ts/artifacts.js";
-import { runAgentReview, runCodexReview, runGeminiReview } from "../lib-ts/reviewers/index.js";
+import { runAgentReview } from "../lib-ts/reviewers/index.js";
+import { DEFAULT_REVIEW_ITERATIONS } from "../lib-ts/state.js";
+import { runPlanQuestions } from "../lib-ts/plan-questions.js";
 
 // ---------------------------------------------------------------------------
 // Hook Name
@@ -113,10 +123,7 @@ function extractTopIssuesForTracker(
   combined: CombinedReviewResult,
   maxCount = 5,
 ): string[] {
-  const allReviewers = [
-    ...Object.values(combined.cli_reviewers),
-    ...Object.values(combined.agents),
-  ];
+  const allReviewers = Object.values(combined.agents);
   const issues: string[] = [];
   for (const r of allReviewers) {
     if (!r.data) continue;
@@ -140,78 +147,68 @@ function extractTopIssuesForTracker(
 // ---------------------------------------------------------------------------
 
 /**
- * Determine which agents should graduate based on their review results.
- * Graduation criteria: verdict === "pass" OR zero high-severity issues.
- * Agents with "skip"/"error" do NOT graduate (no signal).
+ * Determine which agents are pass-eligible this iteration.
+ * Criteria: verdict === "pass" OR zero high-severity issues.
+ * Agents with "skip"/"error" are NOT eligible (no signal).
  */
-function computeGraduated(agentResults: Record<string, ReviewerResult>): string[] {
-  const graduated: string[] = [];
+function computePassEligible(agentResults: Record<string, ReviewerResult>): string[] {
+  const eligible: string[] = [];
   for (const [name, result] of Object.entries(agentResults)) {
     if (result.verdict === "skip" || result.verdict === "error") continue;
-    if (result.verdict === "pass") { graduated.push(name); continue; }
+    if (result.verdict === "pass") { eligible.push(name); continue; }
     const issues = Array.isArray(result.data?.issues)
       ? (result.data.issues as Array<{ severity?: string }>) : [];
     if (issues.filter(i => i.severity === "high").length === 0) {
-      graduated.push(name);
+      eligible.push(name);
     }
   }
-  return graduated;
-}
-
-/**
- * Load the set of graduated agent names from previous iterations.
- * Returns empty set on iteration 1 (no iteration.json exists).
- */
-function loadGraduatedSet(reviewsDir: string): Set<string> {
-  const existing = loadIterationState(reviewsDir);
-  return new Set(existing?.graduated ?? []);
+  return eligible;
 }
 
 // ---------------------------------------------------------------------------
 // Default Configuration
 // ---------------------------------------------------------------------------
 
-const DEFAULT_AGENTS: Array<{ name: string; model: string; focus: string; enabled: boolean; categories: string[] }> = [
-  { name: "handoff-readiness", model: "sonnet", focus: "fresh context execution readiness", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "clarity-auditor", model: "sonnet", focus: "communication clarity and execution readiness", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "skeptic", model: "sonnet", focus: "problem-solution alignment and assumption validation", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "documentation-philosophy", model: "sonnet", focus: "knowledge capture and documentation placement", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "risk-premortem", model: "sonnet", focus: "pre-mortem failure analysis", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "risk-fmea", model: "sonnet", focus: "systematic failure mode analysis", enabled: true, categories: ["code", "infrastructure", "design"] },
-  { name: "risk-dependency", model: "sonnet", focus: "dependency chain and blast radius analysis", enabled: true, categories: ["code", "infrastructure"] },
-  { name: "risk-reversibility", model: "sonnet", focus: "decision reversibility and optionality", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "completeness-gaps", model: "sonnet", focus: "structural gap analysis", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "completeness-feasibility", model: "sonnet", focus: "feasibility and resource analysis", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "completeness-ordering", model: "sonnet", focus: "step ordering and critical path analysis", enabled: true, categories: ["code", "infrastructure", "design"] },
-  { name: "arch-structure", model: "sonnet", focus: "coupling, cohesion, and boundary analysis", enabled: true, categories: ["code", "infrastructure", "design"] },
-  { name: "arch-evolution", model: "sonnet", focus: "evolutionary architecture and change amplification", enabled: true, categories: ["code", "infrastructure", "design"] },
-  { name: "arch-patterns", model: "sonnet", focus: "pattern selection and technology fit", enabled: true, categories: ["code", "infrastructure"] },
-  { name: "verify-coverage", model: "sonnet", focus: "verification coverage mapping", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "verify-strength", model: "sonnet", focus: "test quality and mutation analysis", enabled: true, categories: ["code", "infrastructure"] },
-  { name: "tradeoff-costs", model: "sonnet", focus: "opportunity cost and capability sacrifice", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "tradeoff-stakeholders", model: "sonnet", focus: "stakeholder impact and cost-benefit asymmetry", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "scope-boundary", model: "sonnet", focus: "scope drift and boundary enforcement", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "hidden-complexity", model: "sonnet", focus: "understated complexity and hidden difficulty", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "simplicity-guardian", model: "sonnet", focus: "over-engineering and unnecessary complexity", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "devils-advocate", model: "sonnet", focus: "contrarian analysis and reductio ad absurdum", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "assumption-tracer", model: "sonnet", focus: "dependency chains and foundational assumptions", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "incremental-delivery", model: "sonnet", focus: "incremental delivery and vertical slicing", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
-  { name: "constraint-validator", model: "sonnet", focus: "constraint identification and satisfaction", enabled: true, categories: ["code", "infrastructure", "documentation", "design", "research", "life", "business"] },
+const ALL_CATEGORIES = ["code", "infrastructure", "documentation", "design", "research", "life", "business"];
+const CODE_INFRA_DESIGN = ["code", "infrastructure", "design"];
+const CODE_INFRA = ["code", "infrastructure"];
+const AGENT_DEFAULTS = { model: "sonnet", provider: "claude", enabled: true } as const;
+
+const DEFAULT_AGENTS: Array<{ name: string; model: string; provider: string; focus: string; enabled: boolean; categories: string[] }> = [
+  { ...AGENT_DEFAULTS, name: "handoff-readiness", focus: "fresh context execution readiness", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "clarity-auditor", focus: "communication clarity and execution readiness", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "skeptic", focus: "problem-solution alignment and assumption validation", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "documentation-philosophy", focus: "knowledge capture and documentation placement", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "risk-premortem", focus: "pre-mortem failure analysis", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "risk-fmea", focus: "systematic failure mode analysis", categories: CODE_INFRA_DESIGN },
+  { ...AGENT_DEFAULTS, name: "risk-dependency", focus: "dependency chain and blast radius analysis", categories: CODE_INFRA },
+  { ...AGENT_DEFAULTS, name: "risk-reversibility", focus: "decision reversibility and optionality", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "completeness-gaps", focus: "structural gap analysis", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "completeness-feasibility", focus: "feasibility and resource analysis", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "completeness-ordering", focus: "step ordering and critical path analysis", categories: CODE_INFRA_DESIGN },
+  { ...AGENT_DEFAULTS, name: "arch-structure", focus: "coupling, cohesion, and boundary analysis", categories: CODE_INFRA_DESIGN },
+  { ...AGENT_DEFAULTS, name: "arch-evolution", focus: "evolutionary architecture and change amplification", categories: CODE_INFRA_DESIGN },
+  { ...AGENT_DEFAULTS, name: "arch-patterns", focus: "pattern selection and technology fit", categories: CODE_INFRA },
+  { ...AGENT_DEFAULTS, name: "verify-coverage", focus: "verification coverage mapping", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "verify-strength", focus: "test quality and mutation analysis", categories: CODE_INFRA },
+  { ...AGENT_DEFAULTS, name: "tradeoff-costs", focus: "opportunity cost and capability sacrifice", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "tradeoff-stakeholders", focus: "stakeholder impact and cost-benefit asymmetry", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "scope-boundary", focus: "scope drift and boundary enforcement", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "hidden-complexity", focus: "understated complexity and hidden difficulty", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "simplicity-guardian", focus: "over-engineering and unnecessary complexity", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "devils-advocate", focus: "contrarian analysis and reductio ad absurdum", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "assumption-tracer", focus: "dependency chains and foundational assumptions", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "incremental-delivery", focus: "incremental delivery and vertical slicing", categories: ALL_CATEGORIES },
+  { ...AGENT_DEFAULTS, name: "constraint-validator", focus: "constraint identification and satisfaction", categories: ALL_CATEGORIES },
 ];
 
 const DEFAULT_ORCHESTRATOR: { enabled: boolean; model: string; timeout: number } = { enabled: true, model: "opus", timeout: 60 };
 const DEFAULT_AGENT_MODEL = "sonnet";
 
-const DEFAULT_REVIEW_ITERATIONS: Record<string, number> = {
-  simple: 1,
-  medium: 2,
-  high: 2,
-};
-
 const DEFAULT_AGENT_SELECTION: Record<string, unknown> = {
   simple: { min: 3, max: 3 },
-  medium: { min: 8, max: 8 },
-  high: { min: 12, max: 12 },
+  medium: { min: 5, max: 5 },
+  high: { min: 7, max: 7 },
   fallbackCount: 3,
 };
 
@@ -298,35 +295,71 @@ function saveIterationState(reviewsDir: string, state: IterationState & { schema
   }
 }
 
-function getIterationStateFromContext(
-  reviewsDir: string,
-  complexity: string,
-  config?: Record<string, unknown>,
-): IterationState {
-  const existing = loadIterationState(reviewsDir);
-  if (existing) return existing;
-  const reviewIterations: Record<string, number> = { ...DEFAULT_REVIEW_ITERATIONS };
-  if (config) {
-    const overrides = config.reviewIterations;
-    if (overrides && typeof overrides === "object") {
-      Object.assign(reviewIterations, overrides);
-    }
+// ---------------------------------------------------------------------------
+// Model Provider Assignment
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MODELS_CONFIG: ModelsConfig = {
+  providers: {
+    claude: { enabled: true, models: ["sonnet"] },
+    codex: { enabled: true, models: ["gpt-5.1-codex-mini"] },
+  },
+};
+
+function loadModelsConfig(settings: Record<string, unknown>): ModelsConfig {
+  const raw = settings.models as Record<string, unknown> | undefined;
+  if (!raw?.providers || typeof raw.providers !== "object") {
+    return DEFAULT_MODELS_CONFIG;
   }
-  return {
-    current: 1,
-    max: reviewIterations[complexity] ?? 1,
-    complexity,
-    history: [],
-    graduated: [],
-  };
+  const providers: Record<string, ProviderConfig> = {};
+  for (const [name, cfg] of Object.entries(raw.providers as Record<string, unknown>)) {
+    const c = cfg as Record<string, unknown>;
+    providers[name] = {
+      enabled: c.enabled !== false,
+      models: Array.isArray(c.models) ? (c.models as string[]).filter(Boolean) : [],
+    };
+  }
+  return { providers };
+}
+
+function assignModelsToAgents(
+  agents: AgentConfig[],
+  modelsConfig: ModelsConfig,
+): AgentConfig[] {
+  // Filter to providers that are enabled, have models, AND whose CLI exists
+  const enabledProviders = Object.entries(modelsConfig.providers)
+    .filter(([name, config]) => {
+      if (!config.enabled || config.models.length === 0) return false;
+      const cliName = name === "claude" ? "claude" : name; // CLI name matches provider name
+      const found = findExecutable(cliName);
+      if (!found) {
+        logWarn(HOOK, `Provider '${name}' enabled but CLI '${cliName}' not found on PATH — skipping`);
+      }
+      return !!found;
+    });
+
+  if (enabledProviders.length === 0) {
+    logWarn(HOOK, "No providers with available CLI found, falling back to Claude with agent defaults");
+    return agents.map(a => ({ ...a, provider: "claude" }));
+  }
+
+  return agents.map(agent => {
+    const idx = Math.floor(Math.random() * enabledProviders.length);
+    const entry = enabledProviders[idx];
+    if (!entry) return { ...agent, provider: "claude" };
+    const [providerName, providerConfig] = entry;
+    const modelIdx = Math.floor(Math.random() * providerConfig.models.length);
+    const model = providerConfig.models[modelIdx] ?? providerConfig.models[0] ?? agent.model;
+    return { ...agent, provider: providerName, model };
+  });
 }
 
 // ---------------------------------------------------------------------------
 // Settings Loading
 // ---------------------------------------------------------------------------
 
-function loadSettings(projDir: string): Record<string, any> {
-  const defaults: Record<string, any> = {
+function loadSettings(projDir: string): Record<string, unknown> {
+  const defaults: Record<string, unknown> = {
     planReview: {
       enabled: true,
       reviewers: {
@@ -350,7 +383,7 @@ function loadSettings(projDir: string): Record<string, any> {
   };
 
   const config = loadConfig(projDir);
-  if (!config || Object.keys(config).length === 0) return defaults;
+  if (!config || Object.keys(config).length === 0) return { ...defaults, models: {} };
 
   // Merge planReview
   const planReview = config.planReview ?? {};
@@ -376,14 +409,15 @@ function loadSettings(projDir: string): Record<string, any> {
   mergedAgent.sanitization = { ...DEFAULT_SANITIZATION, ...((configRecord.sanitization as Record<string, unknown>) ?? {}) };
   mergedAgent.reviewIterations = { ...DEFAULT_REVIEW_ITERATIONS, ...agentReview.reviewIterations ?? {} };
 
-  return { planReview: mergedPlan, agentReview: mergedAgent };
+  const modelsRaw = (config as Record<string, unknown>).models ?? {};
+  return { planReview: mergedPlan, agentReview: mergedAgent, models: modelsRaw };
 }
 
 function loadAgentLibrary(
   projDir: string,
-  settings?: Record<string, any>,
+  settings?: Record<string, unknown>,
 ): AgentConfig[] {
-  const agentsData = aggregateAgents(path.join(projDir, "_cc-native", "agents"));
+  const agentsData = aggregateAgents(path.join(projDir, "_cc-native", "agents", "plan-review"));
   const defaultModel = settings?.agentDefaults?.model ?? DEFAULT_AGENT_MODEL;
 
   if (!agentsData || agentsData.length === 0) {
@@ -391,6 +425,7 @@ function loadAgentLibrary(
     return DEFAULT_AGENTS.map(a => ({
       name: a.name,
       model: a.model ?? defaultModel,
+      provider: a.provider ?? "claude",
       focus: a.focus ?? "general review",
       enabled: a.enabled ?? true,
       categories: a.categories ?? ["code"],
@@ -444,8 +479,23 @@ async function main(): Promise<void> {
     return;
   }
 
-  // Find and read plan
-  const planPath = findPlanFile();
+  // Find plan file: prefer transcript-based discovery (session-accurate), fall back to mtime scan
+  const transcriptPath = payload.transcript_path as string | undefined;
+  let planPath: string | null = null;
+
+  if (transcriptPath) {
+    planPath = findPlanPathInTranscript(transcriptPath);
+    if (planPath) {
+      logInfo(HOOK, `Found plan via transcript: ${planPath}`);
+    } else {
+      logDebug(HOOK, "No plan Write found in transcript, falling back to mtime scan");
+    }
+  }
+
+  if (!planPath) {
+    planPath = findPlanFile();
+  }
+
   if (!planPath) {
     skipWithInfo("No plan file found in ~/.claude/plans/. The plan may not have been written yet.");
     return;
@@ -467,6 +517,43 @@ async function main(): Promise<void> {
   logInfo(HOOK, `Found plan at: ${planPath}`);
   logDebug(HOOK, `Plan length: ${plan.length} chars`);
 
+  // ============================================
+  // Questions Gate: ask user questions before review
+  // ============================================
+  if (!wasQuestionsAsked(sessionId, base)) {
+    logInfo(HOOK, "Questions gate: user has not been asked questions yet, running plan-questions agent");
+    const timeout = typeof (settings.agentReview ?? {}).timeout === "number"
+      ? (settings.agentReview as Record<string, unknown>).timeout as number : 120;
+    const questionsResult = await runPlanQuestions(plan, aiwcliDir, timeout, undefined, sessionId);
+
+    // Mark questions as asked NOW — prevents infinite gate loop if Claude
+    // doesn't use AskUserQuestion after denial. Gate fires at most once.
+    markQuestionsAsked(sessionId, base);
+
+    const hasQuestions = questionsResult && (
+      questionsResult.questions.length > 0 ||
+      questionsResult.assumptions.length > 0 ||
+      questionsResult.ambiguities.length > 0
+    );
+
+    if (hasQuestions) {
+      const questionsList = questionsResult.questions.map((q: string, i: number) => `${i + 1}. ${q}`).join("\n");
+      const assumptionsList = questionsResult.assumptions.length > 0
+        ? `\n\nAssumptions detected:\n${questionsResult.assumptions.map((a: string) => `- ${a}`).join("\n")}`
+        : "";
+      const ambiguitiesList = questionsResult.ambiguities.length > 0
+        ? `\n\nAmbiguities detected:\n${questionsResult.ambiguities.map((a: string) => `- ${a}`).join("\n")}`
+        : "";
+      const contextMsg = `## Plan Questions (from independent review)\n\nAn agent reviewed your plan in a fresh context — without access to your session history or codebase exploration. It identified these questions:\n\n${questionsList}${assumptionsList}${ambiguitiesList}\n\nAsk the user these questions using AskUserQuestion before submitting the plan.`;
+      emitContextAndBlock(contextMsg, "Ask the user clarifying questions before submitting the plan. Use AskUserQuestion with the questions above.");
+      return;
+    }
+
+    logInfo(HOOK, "Questions gate: no questions generated, proceeding to review");
+  } else {
+    logInfo(HOOK, "Questions gate: questions already asked, skipping");
+  }
+
   const planHash = computePlanHash(plan);
   logDiagnostic(HOOK, "receive", `plan_size=${plan.length}, session=${sessionId.slice(0, 8)}`, {
     inputs: { plan_hash: planHash, plan_size: plan.length, session_id: sessionId.slice(0, 12) },
@@ -489,42 +576,57 @@ async function main(): Promise<void> {
   // Plan-hash deduplication
   logDebug(HOOK, `Plan hash: ${planHash}`);
   if (isPlanAlreadyReviewed(sessionId, planHash, base)) {
+    const lastReview = getLastPlanReview(sessionId, planHash, base);
+
     if (wasPlanPreviouslyDenied(sessionId, planHash, base)) {
+      // Plan unchanged since last FAIL verdict
       emitContextAndBlock(
         "[Plan Review] Plan content unchanged since last review which found issues.",
         "Plan unchanged since denial. Modify the plan to address review findings, then attempt ExitPlanMode again.",
       );
       return;
     } else {
-      skipWithInfo("Plan already reviewed and approved (same hash).");
+      // Plan already reviewed with PASS or WARN verdict - skip review
+      const verdict = lastReview?.iteration?.latest_verdict || "pass";
+      const skipMsg = `[Plan Review] Plan already reviewed (verdict: ${verdict}). Skipping re-review.`;
+      emitContext(skipMsg);
+      logInfo(HOOK, skipMsg);
       return;
     }
   }
 
+  // Single load of iteration state — reused throughout, saved once at end.
+  // Default max=1 is safe: first iteration 1>1=false (runs), Edit E updates max from config before save.
+  let iterationState: IterationState = loadIterationState(reviewsDir) ?? {
+    current: 1, max: 1, complexity: "medium",
+    history: [], graduated: [], passStreaks: {}, lastPlanHash: "",
+  };
+
+  // Log plan hash changes for diagnostics (iteration counter no longer resets —
+  // plans change every iteration as Claude addresses feedback, so resetting
+  // would keep iteration perpetually at 1).
+  const lastHash = iterationState.lastPlanHash ?? "";
+  if (lastHash && lastHash !== planHash) {
+    logInfo(HOOK, `Plan hash changed (${lastHash.slice(0, 8)}→${planHash.slice(0, 8)}), iteration continues at ${iterationState.current}`);
+  }
+
   // Early iteration check: if we've exhausted max iterations, allow plan through
-  const earlyIterState = loadIterationState(reviewsDir);
-  if (earlyIterState && earlyIterState.current > earlyIterState.max) {
-    skipWithInfo(`Max review iterations reached (${earlyIterState.current - 1}/${earlyIterState.max}), allowing plan through.`);
+  if (iterationState.current > iterationState.max) {
+    skipWithInfo(`Max review iterations reached (${iterationState.current - 1}/${iterationState.max}), allowing plan through.`);
     return;
   }
 
   // Initialize result containers
-  const cliResults: Record<string, ReviewerResult> = {};
   let orchResult: OrchestratorResult | null = null;
   const agentResults: Record<string, ReviewerResult> = {};
-  let allVerdicts: Verdict[] = [];
-  let iterationState: IterationState | null = null;
   let detectedComplexity = "medium";
 
   // ============================================
-  // PHASE 1 & 2: CLI Reviewers + Orchestrator (PARALLEL)
+  // PHASE 1: Orchestrator (Complexity Analysis)
   // ============================================
-  const reviewersConfig = planReviewEnabled ? (planSettings.reviewers ?? {}) : {};
-  const codexEnabled = planReviewEnabled && (reviewersConfig.codex?.enabled ?? true);
-  const geminiEnabled = planReviewEnabled && (reviewersConfig.gemini?.enabled ?? false);
 
-  // Load graduated agents from previous iterations (empty on iteration 1)
-  const graduatedSet = loadGraduatedSet(reviewsDir);
+  // Graduated agents from previous iterations (empty after hash reset or on iteration 1)
+  const graduatedSet = new Set(iterationState.graduated);
   if (graduatedSet.size > 0) {
     logInfo(HOOK, `Graduated agents from previous iterations: ${[...graduatedSet].sort().join(", ")}`);
   }
@@ -546,7 +648,6 @@ async function main(): Promise<void> {
   const alwaysMandatory = resolveMandatoryAgents(mandatoryConfig, "simple");
   let mandatoryNames = alwaysMandatory;
 
-  logDebug(HOOK, `Codex enabled: ${codexEnabled}, Gemini enabled: ${geminiEnabled}`);
   logDebug(HOOK, `Agent library: ${agentLibrary.map(a => a.name)}`);
   logDebug(HOOK, `Mandatory agents: ${[...mandatoryNames].sort()}`);
   logDebug(HOOK, `Orchestrator enabled: ${orchestratorConfig.enabled}`);
@@ -554,18 +655,6 @@ async function main(): Promise<void> {
   // Build phase 1 tasks as promises
   const phase1Promises: Array<{ name: string; promise: Promise<ReviewerResult | OrchestratorResult> }> = [];
 
-  if (codexEnabled) {
-    phase1Promises.push({
-      name: "codex",
-      promise: runCodexReview(plan, REVIEW_SCHEMA, planSettings),
-    });
-  }
-  if (geminiEnabled) {
-    phase1Promises.push({
-      name: "gemini",
-      promise: runGeminiReview(plan, REVIEW_SCHEMA, planSettings),
-    });
-  }
   if (orchestratorConfig.enabled && enabledAgents.length > 0 && !legacyMode) {
     phase1Promises.push({
       name: "orchestrator",
@@ -594,9 +683,7 @@ async function main(): Promise<void> {
     }
   }
 
-  // Collect CLI results
-  if (phase1Results.codex) cliResults.codex = phase1Results.codex as ReviewerResult;
-  if (phase1Results.gemini) cliResults.gemini = phase1Results.gemini as ReviewerResult;
+  // Collect orchestrator result
   if (phase1Results.orchestrator) orchResult = phase1Results.orchestrator as OrchestratorResult;
 
   // ============================================
@@ -606,7 +693,7 @@ async function main(): Promise<void> {
     logInfo(HOOK, "=== PHASE 2: Agent Selection ===");
 
     let selectedAgents: AgentConfig[] = [];
-    const fallbackByComplexity = agentSettings.fallbackByComplexity ?? { simple: 0, medium: 5, high: 9 };
+    const fallbackByComplexity = agentSettings.fallbackByComplexity ?? { simple: 0, medium: 2, high: 4 };
 
     if (enabledAgents.length > 0) {
       let mandatoryAgents = enabledAgents.filter(a => mandatoryNames.has(a.name));
@@ -671,11 +758,19 @@ async function main(): Promise<void> {
       },
     });
 
-    // Initialize iteration state
-    if (reviewsDir) {
-      iterationState = getIterationStateFromContext(reviewsDir, detectedComplexity, agentSettings);
-      logDebug(HOOK, `Iteration state: ${iterationState.current}/${iterationState.max} (${detectedComplexity})`);
-    }
+    // Update complexity/max on the already-loaded iteration state (no second disk read)
+    const reviewIterations: Record<string, number> = {
+      ...DEFAULT_REVIEW_ITERATIONS,
+      ...(agentSettings.reviewIterations ?? {}),
+    };
+    iterationState.complexity = detectedComplexity;
+    iterationState.max = reviewIterations[detectedComplexity] ?? iterationState.max;
+    logDebug(HOOK, `Iteration state: ${iterationState.current}/${iterationState.max} (${detectedComplexity})`);
+
+    // Assign random providers + models to selected agents
+    const modelsConfig = loadModelsConfig(settings);
+    selectedAgents = assignModelsToAgents(selectedAgents, modelsConfig);
+    logInfo(HOOK, `Model assignments: ${selectedAgents.map(a => `${a.name}→${a.provider}:${a.model}`).join(", ")}`);
 
     // PHASE 3: Run selected agents in parallel
     if (selectedAgents.length > 0) {
@@ -716,20 +811,36 @@ async function main(): Promise<void> {
   }
 
   // ============================================
-  // Persist newly graduated agents (before verdict overrides)
+  // Enforce per-agent issue limit (truncate to top N by severity)
+  // ============================================
+  const maxIssuesPerAgent = typeof agentSettings.maxIssuesPerAgent === "number"
+    ? agentSettings.maxIssuesPerAgent : 3;
+
+  for (const r of Object.values(agentResults)) {
+    if (!Array.isArray(r.data?.issues)) continue;
+    const issues = r.data.issues as Array<{ severity?: string }>;
+    if (issues.length <= maxIssuesPerAgent) continue;
+    const severityOrder: Record<string, number> = { high: 0, medium: 1, low: 2 };
+    issues.sort((a, b) => (severityOrder[a.severity ?? "low"] ?? 2) - (severityOrder[b.severity ?? "low"] ?? 2));
+    const originalCount = issues.length;
+    r.data.issues = issues.slice(0, maxIssuesPerAgent);
+    logInfo(HOOK, `${r.name}: truncated issues ${originalCount} → ${maxIssuesPerAgent}`);
+  }
+
+  // ============================================
+  // Compute pass-eligible agents (before verdict overrides)
   // ============================================
-  const newlyGraduated = computeGraduated(agentResults);
-  if (newlyGraduated.length > 0) {
-    logInfo(HOOK, `Newly graduated agents: ${newlyGraduated.join(", ")}`);
+  const passEligible = computePassEligible(agentResults);
+  if (passEligible.length > 0) {
+    logInfo(HOOK, `Pass-eligible agents this iteration: ${passEligible.join(", ")}`);
   }
 
   // ============================================
   // Per-agent high-severity threshold: override verdict to "fail"
   // ============================================
   const highIssueThreshold = typeof agentSettings.highIssueThreshold === "number" ? agentSettings.highIssueThreshold : 3;
-  allVerdicts = [];
 
-  for (const r of [...Object.values(cliResults), ...Object.values(agentResults)]) {
+  for (const r of Object.values(agentResults)) {
     if (!r.verdict || r.verdict === "skip" || r.verdict === "error") continue;
     const issues = Array.isArray(r.data?.issues) ? r.data.issues as Array<{ severity?: string }> : [];
     const agentHigh = issues.filter(i => i.severity === "high").length;
@@ -739,7 +850,6 @@ async function main(): Promise<void> {
       verdict = "fail";
       r.verdict = verdict;
     }
-    allVerdicts.push(verdict);
   }
 
   // ============================================
@@ -747,7 +857,7 @@ async function main(): Promise<void> {
   // ============================================
   logInfo(HOOK, "=== PHASE 4: Generate Output ===");
 
-  if (Object.keys(cliResults).length === 0 && Object.keys(agentResults).length === 0) {
+  if (Object.keys(agentResults).length === 0) {
     if (graduatedSet.size > 0 && originalAgentCount > 0) {
       skipWithInfo("All agent reviewers graduated from previous iterations — no review needed.");
     } else {
@@ -756,12 +866,17 @@ async function main(): Promise<void> {
     return;
   }
 
-  const overall = allVerdicts.length > 0 ? worstVerdict(allVerdicts) : "pass";
+  // Review decision — corroboration-based (proportional threshold per dimension)
+  // Must be computed before writeCombinedArtifacts and buildInlineReviewSummary which consume it.
+  const allReviewerResults: Record<string, ReviewerResult> = agentResults;
+  const corroborationResult = computeCorroboratedDecision(allReviewerResults);
+
+  // Use corroboration verdict as single source of truth (not worstVerdict from individual agents)
+  const overall = corroborationResult.verdict;
 
   const combinedResult: CombinedReviewResult = {
     plan_hash: planHash,
     overall_verdict: overall,
-    cli_reviewers: cliResults,
     orchestration: orchResult,
     agents: agentResults,
     timestamp: new Date().toISOString(),
@@ -774,7 +889,7 @@ async function main(): Promise<void> {
   const combinedSettings = { display: displaySettings };
 
   // Get current iteration number
-  const currentIteration = iterationState?.current ?? 1;
+  const currentIteration = iterationState.current;
 
   // Create review folder
   const reviewFolder = getReviewFolderPath(contextId, currentIteration, base);
@@ -790,9 +905,16 @@ async function main(): Promise<void> {
     undefined,
     reviewFolder,
     currentIteration,
+    corroborationResult,
   );
   logInfo(HOOK, `Saved review: ${reviewFile}`);
 
+  // Write corroboration analysis report
+  const corroborationReport = buildCorroborationReport(corroborationResult);
+  const corroborationPath = path.join(reviewFolder, "corroboration.md");
+  fs.writeFileSync(corroborationPath, corroborationReport, "utf-8");
+  logInfo(HOOK, `Saved corroboration report: ${corroborationPath}`);
+
   // Save plan snapshot for diffing between iterations
   try {
     fs.writeFileSync(path.join(reviewFolder, "plan.md"), plan, "utf-8");
@@ -802,16 +924,16 @@ async function main(): Promise<void> {
   }
 
   // Build inline summary with top issues (always emitted, even on pass)
-  const inlineSummary = buildInlineReviewSummary(combinedResult);
+  const inlineSummary = buildInlineReviewSummary(combinedResult, 5, 800, corroborationResult);
   const topIssuesList = extractTopIssuesForTracker(combinedResult, 5);
   const contextParts = [inlineSummary];
   if (topIssuesList.length > 0) {
     contextParts.push(`\nTop high-severity issues:\n${topIssuesList.map(i => `- ${i}`).join("\n")}`);
   }
   contextParts.push(`\nFull review: \`${reviewFile}\`\n`);
-
-  // Review decision
-  const { should_deny: shouldDeny, reason: denyReason, score: reviewScore } = computeReviewDecision(allVerdicts);
+  const shouldDeny = corroborationResult.blocking.length > 0;
+  const denyReason = shouldDeny ? "corroborated_issues" : "no_corroboration";
+  const reviewScore = shouldDeny ? 1.0 : 0.0;
 
   logInfo(HOOK, `REVIEW_DECISION: verdict=${combinedResult.overall_verdict}, deny=${shouldDeny}, reason=${denyReason}, score=${reviewScore.toFixed(2)}`);
   logDiagnostic(HOOK, "result", `verdict=${combinedResult.overall_verdict}, deny=${shouldDeny}, reason=${denyReason}`, {
@@ -820,7 +942,6 @@ async function main(): Promise<void> {
     inputs: {
       overall_verdict: combinedResult.overall_verdict,
       review_score: Math.round(reviewScore * 100) / 100,
-      cli_count: Object.keys(cliResults).length,
       agent_count: Object.keys(agentResults).length,
     },
   });
@@ -833,34 +954,51 @@ async function main(): Promise<void> {
   }
 
   // Iteration logic:
-  // - On FAIL at max: extend max by 1 (grant one more revision chance)
-  // - On WARN: block but do NOT extend max (warns don't earn extra iterations)
-  // - On PASS: jump current to max so next call triggers early exit (no more reviews)
-  const isFail = overall === "fail";
-  if (iterationState && reviewsDir) {
+  // - On PASS/WARRANT: set current past max so no more reviews happen
+  // - On DENY (fail/warn): increment current toward max (safety valve)
+  // - Max iterations (high=5, medium=3, simple=1) caps total reviews before auto-allow
+  if (reviewsDir) {
     iterationState.history.push({ hash: planHash, verdict: overall, timestamp: new Date().toISOString() });
-
-    if (isFail && iterationState.current >= iterationState.max) {
-      iterationState.max += 1;
-      logInfo(HOOK, `Extending max iterations to ${iterationState.max} due to fail at boundary (${iterationState.current}/${iterationState.max})`);
-    }
+    iterationState.lastPlanHash = planHash;
 
     if (!shouldDeny) {
-      // Pass: set current to max so next call (current+1 > max) triggers early exit
-      iterationState.current = iterationState.max;
-      logInfo(HOOK, `Pass: setting current to max (${iterationState.max}) to exhaust iterations`);
+      // Pass/warrant: stop iterating — set current past max
+      iterationState.current = iterationState.max + 1;
+      logInfo(HOOK, `Pass/warrant: stopping iterations`);
+    } else {
+      // Deny: advance iteration counter toward max so safety valve triggers
+      iterationState.current += 1;
+      logInfo(HOOK, `Deny: advancing iteration (${iterationState.current}/${iterationState.max})`);
     }
 
-    // Merge newly graduated agents into persistent state
-    if (newlyGraduated.length > 0) {
-      const allGraduated = new Set([
-        ...(iterationState.graduated ?? []),
-        ...newlyGraduated,
-      ]);
-      iterationState.graduated = [...allGraduated];
+    // Update pass streaks — only for agents that actually ran this iteration
+    const passStreaks = { ...(iterationState.passStreaks ?? {}) };
+    const passEligibleSet = new Set(passEligible);
+    const graduatedSetCurrent = new Set(iterationState.graduated);
+
+    for (const name of Object.keys(agentResults)) {
+      if (graduatedSetCurrent.has(name)) continue;
+      if (passEligibleSet.has(name)) {
+        passStreaks[name] = (passStreaks[name] ?? 0) + 1;
+      } else {
+        passStreaks[name] = 0;
+      }
+    }
+    iterationState.passStreaks = passStreaks;
+
+    // Graduate agents that reached threshold
+    const GRADUATION_THRESHOLD = 2;
+    const newGrads: string[] = [];
+    for (const [name, streak] of Object.entries(passStreaks)) {
+      if (streak >= GRADUATION_THRESHOLD && !graduatedSetCurrent.has(name)) {
+        newGrads.push(name);
+      }
+    }
+    if (newGrads.length > 0) {
+      iterationState.graduated = [...iterationState.graduated, ...newGrads];
+      logInfo(HOOK, `Newly graduated (${GRADUATION_THRESHOLD} consecutive passes): ${newGrads.join(", ")}`);
     }
 
-    iterationState.current += 1;
     saveIterationState(reviewsDir, iterationState);
   }
 
@@ -874,13 +1012,14 @@ async function main(): Promise<void> {
     verdict: combinedResult.overall_verdict,
     decision: trackerDecision,
     score: reviewScore,
-    topIssues: extractTopIssuesForTracker(combinedResult, 5),
+    topIssues: topIssuesList,
     reviewFolder,
   };
   writeReviewTracker(ccNativeReviewsDir, trackerEntry);
   logInfo(HOOK, `Updated review tracker: ${path.join(ccNativeReviewsDir, "review-tracker.md")}`);
 
-  // Emit output — always emit context with top issues + link; block only on fail
+  // ALL first-time reviews block ExitPlanMode and inject feedback
+  // Verdict controls iteration logic and next-run skip decision only
   const contextText = contextParts.join("");
 
   logDebug(HOOK, `REVIEW_CONTEXT_INJECTED: chars=${contextText.length}, inline_chars=${inlineSummary.length}`);
@@ -888,33 +1027,34 @@ async function main(): Promise<void> {
   const REVIEWER_CAVEAT = "Reviewers have limited context compared to your full session — use your judgment to adopt valid points and dismiss genuine false positives. However, treat false positives as a clarity signal: if a reviewer misunderstood your plan, an agent executing it will likely hit the same confusion. Revise those sections to be unambiguous so no future reader — human or AI — makes the same mistake.";
   const RESUBMIT_INSTRUCTION = "IMPORTANT: After revising the plan file, you MUST call ExitPlanMode again to trigger re-review. Do not end your turn or ask the user without calling ExitPlanMode.";
 
+  const iterInfo = ` (iteration ${iterationState.current - 1}/${iterationState.max}, score=${reviewScore.toFixed(2)})`;
+
   if (shouldDeny) {
-    const disposition = iterationState
-      ? `hook_deny_iter_${iterationState.current - 1}`
-      : "hook_deny";
-    markPlanReviewed(sessionId, planHash, base, HOOK, iterationState ?? undefined, disposition);
+    // FAIL verdict - critical issues found
+    const disposition = `hook_deny_iter_${iterationState.current - 1}`;
+    markPlanReviewed(sessionId, planHash, base, HOOK, iterationState, disposition);
     const topIssuesText = extractTopIssuesText(combinedResult, 3, "high");
-    const highIssuesDoc = buildHighIssuesDocument(combinedResult);
+    const highIssuesDoc = buildHighIssuesDocument(combinedResult, corroborationResult);
     const highIssuesPath = path.join(reviewFolder, "high-issues.md");
     fs.writeFileSync(highIssuesPath, highIssuesDoc, "utf-8");
 
-    const iterInfo = iterationState
-      ? ` (iteration ${iterationState.current - 1}/${iterationState.max}, score=${reviewScore.toFixed(2)})`
-      : ` (score=${reviewScore.toFixed(2)})`;
-
-    emitContextAndBlock(
-      contextText,
-      `Plan review FAILED${iterInfo}. ` +
+    const blockReason = `Plan review FAILED${iterInfo}. ` +
       `Critical issues: ${topIssuesText}. ` +
       `IMPORTANT: Read \`${highIssuesPath}\` for ALL high-severity issues — ` +
       `this file contains only the most critical findings, no noise. ` +
       `${REVIEWER_CAVEAT} ` +
       `Revise the plan to address these issues, then call ExitPlanMode again. ` +
-      RESUBMIT_INSTRUCTION,
-    );
+      RESUBMIT_INSTRUCTION;
+
+    emitContextAndBlock(contextText, blockReason);
   } else {
-    markPlanReviewed(sessionId, planHash, base, HOOK, iterationState ?? undefined, "allow");
-    emitContext(contextText);
+    // PASS or WARN verdict - block to inject feedback, but mark as allowed
+    const disposition = `hook_allow_iter_${iterationState.current - 1}`;
+    markPlanReviewed(sessionId, planHash, base, HOOK, iterationState, disposition);
+
+    const blockReason = `Plan review ${overall.toUpperCase()}${iterInfo}. Review complete. ${REVIEWER_CAVEAT}`;
+
+    emitContextAndBlock(contextText, blockReason);
   }
 }