aiwcli 0.11.1 → 0.12.1

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

@@ -19,11 +19,12 @@
  *   - reviewer-output/{reviewer}.json (individual reviewer results)
  */
 
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
-import * as path from "node:path";
 import * as os from "node:os";
-import * as crypto from "node:crypto";
+import * as path from "node:path";
 
+import { getProjectRoot, getAiwcliDir, getContextReviewsDir, getContextDir, getReviewFolderPath } from "../../_shared/lib-ts/base/constants.js";
 import {
   loadHookInput,
   runHookAsync,
@@ -36,11 +37,40 @@ import {
   emitContextAndBlock,
 } from "../../_shared/lib-ts/base/hook-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 { ContextState } from "../../_shared/lib-ts/types.js";
+import { aggregateAgents } from "../lib-ts/aggregate-agents.js";
+import {
+  writeCombinedArtifacts,
+  buildInlineReviewSummary,
+  extractTopIssuesText,
+  buildHighIssuesDocument,
+  buildCorroborationReport,
+  writeReviewTracker,
+} from "../lib-ts/artifacts.js";
+import type { ReviewTrackerEntry } from "../lib-ts/artifacts.js";
+import {
+  isPlanAlreadyReviewed,
+  wasPlanPreviouslyDenied,
+  getLastPlanReview,
+  markPlanReviewed,
+  wasPlanQuestionsAgentAsked,
+  markQuestionsAsked,
+} from "../lib-ts/cc-native-state.js";
+import { loadConfig, getDisplaySettings } from "../lib-ts/config.js";
+import { computeCorroboratedDecision } from "../lib-ts/corroboration.js";
+import { debugLog } from "../lib-ts/debug.js";
+import { runOrchestrator } from "../lib-ts/orchestrator.js";
+import { runPlanQuestions } from "../lib-ts/plan-questions.js";
+import { runAgentReview } from "../lib-ts/reviewers/index.js";
+import { DEFAULT_REVIEW_ITERATIONS } from "../lib-ts/state.js";
+import {
+  REVIEW_SCHEMA,
+  DEFAULT_DISPLAY,
+  DEFAULT_SANITIZATION,
+} from "../lib-ts/types.js";
 import type {
   AgentConfig,
   OrchestratorConfig,
@@ -52,35 +82,7 @@ import type {
   Verdict,
   IterationState,
 } from "../lib-ts/types.js";
-import type { ContextState } from "../../_shared/lib-ts/types.js";
-import {
-  REVIEW_SCHEMA,
-  DEFAULT_DISPLAY,
-  DEFAULT_SANITIZATION,
-} from "../lib-ts/types.js";
-
-import {
-  isPlanAlreadyReviewed,
-  wasPlanPreviouslyDenied,
-  markPlanReviewed,
-} from "../lib-ts/cc-native-state.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";
-import { debugLog } from "../lib-ts/debug.js";
-import {
-  writeCombinedArtifacts,
-  buildInlineReviewSummary,
-  extractTopIssuesText,
-  buildHighIssuesDocument,
-  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 { DEFAULT_REVIEW_ITERATIONS } from "../lib-ts/state.js";
 
 // ---------------------------------------------------------------------------
 // Hook Name
@@ -118,10 +120,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;
@@ -224,7 +223,7 @@ function resolveMandatoryAgents(
     return new Set(configValue as string[]);
   }
   if (!configValue || typeof configValue !== "object") {
-    return new Set(["handoff-readiness", "clarity-auditor", "skeptic"]);
+    return new Set(["clarity-auditor", "handoff-readiness", "skeptic"]);
   }
   const cfg = configValue as Record<string, string[]>;
   const names = new Set(cfg.always ?? []);
@@ -274,8 +273,8 @@ function loadIterationState(reviewsDir: string): IterationState | null {
   if (!fs.existsSync(iterationFile)) return null;
   try {
     return JSON.parse(fs.readFileSync(iterationFile, "utf-8")) as IterationState;
-  } catch (e) {
-    logError(HOOK, `Failed to load iteration state: ${e}`);
+  } catch (error) {
+    logError(HOOK, `Failed to load iteration state: ${error}`);
     return null;
   }
 }
@@ -287,8 +286,8 @@ function saveIterationState(reviewsDir: string, state: IterationState & { schema
     state.schema_version = "1.0.0";
     fs.writeFileSync(iterationFile, JSON.stringify(state, null, 2), "utf-8");
     return true;
-  } catch (e) {
-    logError(HOOK, `Failed to save iteration state: ${e}`);
+  } catch (error) {
+    logError(HOOK, `Failed to save iteration state: ${error}`);
     return false;
   }
 }
@@ -333,7 +332,7 @@ function assignModelsToAgents(
       if (!found) {
         logWarn(HOOK, `Provider '${name}' enabled but CLI '${cliName}' not found on PATH — skipping`);
       }
-      return !!found;
+      return Boolean(found);
     });
 
   if (enabledProviders.length === 0) {
@@ -401,11 +400,11 @@ function loadSettings(projDir: string): Record<string, unknown> {
   }
   mergedAgent.display = getDisplaySettings(config, "agentReview");
   const configRecord = config as Record<string, unknown>;
-  mergedAgent.agentSelection = { ...DEFAULT_AGENT_SELECTION, ...((configRecord.agentSelection as Record<string, unknown>) ?? {}) };
-  mergedAgent.agentDefaults = { model: DEFAULT_AGENT_MODEL, ...((configRecord.agentDefaults as Record<string, unknown>) ?? {}) };
+  mergedAgent.agentSelection = { ...DEFAULT_AGENT_SELECTION, ...(configRecord.agentSelection as Record<string, unknown>) };
+  mergedAgent.agentDefaults = { model: DEFAULT_AGENT_MODEL, ...(configRecord.agentDefaults as Record<string, unknown>) };
   mergedAgent.complexityCategories = (configRecord.complexityCategories as string[]) ?? [...DEFAULT_COMPLEXITY_CATEGORIES];
-  mergedAgent.sanitization = { ...DEFAULT_SANITIZATION, ...((configRecord.sanitization as Record<string, unknown>) ?? {}) };
-  mergedAgent.reviewIterations = { ...DEFAULT_REVIEW_ITERATIONS, ...agentReview.reviewIterations ?? {} };
+  mergedAgent.sanitization = { ...DEFAULT_SANITIZATION, ...(configRecord.sanitization as Record<string, unknown>) };
+  mergedAgent.reviewIterations = { ...DEFAULT_REVIEW_ITERATIONS, ...agentReview.reviewIterations };
 
   const modelsRaw = (config as Record<string, unknown>).models ?? {};
   return { planReview: mergedPlan, agentReview: mergedAgent, models: modelsRaw };
@@ -415,7 +414,7 @@ function loadAgentLibrary(
   projDir: string,
   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) {
@@ -502,8 +501,8 @@ async function main(): Promise<void> {
   let plan: string;
   try {
     plan = fs.readFileSync(planPath, "utf-8").trim();
-  } catch (e) {
-    skipWithInfo(`Failed to read plan file: ${e}`);
+  } catch (error) {
+    skipWithInfo(`Failed to read plan file: ${error}`);
     return;
   }
 
@@ -515,6 +514,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 (!wasPlanQuestionsAgentAsked(sessionId, base)) {
+    logInfo(HOOK, "Questions gate (Phase B): plan-questions agent has not run yet, running now");
+    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 agent questions as asked NOW — prevents infinite gate loop if Claude
+    // doesn't use AskUserQuestion after denial. Gate fires at most once.
+    markQuestionsAsked(sessionId, base, "agent");
+
+    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 (Phase B): no questions generated, proceeding to review");
+  } else {
+    logInfo(HOOK, "Questions gate (Phase B): agent already ran, 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) },
@@ -537,31 +573,38 @@ 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) ?? {
+  const iterationState: IterationState = loadIterationState(reviewsDir) ?? {
     current: 1, max: 1, complexity: "medium",
     history: [], graduated: [], passStreaks: {}, lastPlanHash: "",
   };
 
-  // Reset iteration counter when plan content changes (BEFORE early exit check)
-  // Graduation state (graduated[], passStreaks{}) persists across plan changes.
+  // 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)}), resetting iteration counter`);
-    iterationState.current = 1;
+    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
@@ -571,19 +614,13 @@ async function main(): Promise<void> {
   }
 
   // Initialize result containers
-  const cliResults: Record<string, ReviewerResult> = {};
   let orchResult: OrchestratorResult | null = null;
   const agentResults: Record<string, ReviewerResult> = {};
-  let allVerdicts: Verdict[] = [];
   let detectedComplexity = "medium";
 
   // ============================================
-  // PHASE 1 & 2: CLI Reviewers + Orchestrator (PARALLEL)
+  // PHASE 1: Orchestrator (Complexity Analysis)
   // ============================================
-  const reviewersConfig = planReviewEnabled ? (planSettings.reviewers ?? {}) : {};
-  // Deprecated: agents now support Codex provider via models.providers.codex
-  const codexEnabled = planReviewEnabled && (reviewersConfig.codex?.enabled ?? false);
-  const geminiEnabled = planReviewEnabled && (reviewersConfig.gemini?.enabled ?? false);
 
   // Graduated agents from previous iterations (empty after hash reset or on iteration 1)
   const graduatedSet = new Set(iterationState.graduated);
@@ -608,7 +645,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}`);
@@ -616,18 +652,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",
@@ -656,9 +680,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;
 
   // ============================================
@@ -736,7 +758,7 @@ async function main(): Promise<void> {
     // Update complexity/max on the already-loaded iteration state (no second disk read)
     const reviewIterations: Record<string, number> = {
       ...DEFAULT_REVIEW_ITERATIONS,
-      ...(agentSettings.reviewIterations ?? {}),
+      ...agentSettings.reviewIterations,
     };
     iterationState.complexity = detectedComplexity;
     iterationState.max = reviewIterations[detectedComplexity] ?? iterationState.max;
@@ -791,7 +813,7 @@ async function main(): Promise<void> {
   const maxIssuesPerAgent = typeof agentSettings.maxIssuesPerAgent === "number"
     ? agentSettings.maxIssuesPerAgent : 3;
 
-  for (const r of [...Object.values(cliResults), ...Object.values(agentResults)]) {
+  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;
@@ -814,19 +836,17 @@ async function main(): Promise<void> {
   // 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;
-    let verdict = r.verdict;
+    let {verdict} = r;
     if (agentHigh >= highIssueThreshold) {
       logInfo(HOOK, `${r.name}: verdict overridden to 'fail' (${agentHigh} high issues >= ${highIssueThreshold})`);
       verdict = "fail";
       r.verdict = verdict;
     }
-    allVerdicts.push(verdict);
   }
 
   // ============================================
@@ -834,7 +854,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 {
@@ -843,20 +863,25 @@ 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(),
   };
 
   const displaySettings = {
-    ...(planSettings.display ?? {}),
-    ...(agentSettings.display ?? {}),
+    ...planSettings.display,
+    ...agentSettings.display,
   };
   const combinedSettings = { display: displaySettings };
 
@@ -868,11 +893,6 @@ async function main(): Promise<void> {
   fs.mkdirSync(reviewFolder, { recursive: true });
   logInfo(HOOK, `Created review folder: ${reviewFolder}`);
 
-  // Review decision — corroboration-based (proportional threshold per dimension)
-  // Must be computed before writeCombinedArtifacts and buildInlineReviewSummary which consume it.
-  const allReviewerResults: Record<string, ReviewerResult> = { ...cliResults, ...agentResults };
-  const corroborationResult = computeCorroboratedDecision(allReviewerResults);
-
   const reviewFile = writeCombinedArtifacts(
     base,
     plan,
@@ -886,12 +906,18 @@ async function main(): Promise<void> {
   );
   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");
     logDebug(HOOK, `Saved plan snapshot: ${path.join(reviewFolder, "plan.md")}`);
-  } catch (e) {
-    logWarn(HOOK, `Failed to save plan snapshot: ${e}`);
+  } catch (error) {
+    logWarn(HOOK, `Failed to save plan snapshot: ${error}`);
   }
 
   // Build inline summary with top issues (always emitted, even on pass)
@@ -904,7 +930,7 @@ async function main(): Promise<void> {
   contextParts.push(`\nFull review: \`${reviewFile}\`\n`);
   const shouldDeny = corroborationResult.blocking.length > 0;
   const denyReason = shouldDeny ? "corroborated_issues" : "no_corroboration";
-  const reviewScore = shouldDeny ? 1.0 : 0.0;
+  const reviewScore = shouldDeny ? 1 : 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}`, {
@@ -913,7 +939,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,
     },
   });
@@ -944,7 +969,7 @@ async function main(): Promise<void> {
     }
 
     // Update pass streaks — only for agents that actually ran this iteration
-    const passStreaks = { ...(iterationState.passStreaks ?? {}) };
+    const passStreaks = { ...iterationState.passStreaks };
     const passEligibleSet = new Set(passEligible);
     const graduatedSetCurrent = new Set(iterationState.graduated);
 
@@ -990,7 +1015,8 @@ async function main(): Promise<void> {
   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}`);
@@ -998,7 +1024,10 @@ 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) {
+    // 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");
@@ -1006,21 +1035,23 @@ async function main(): Promise<void> {
     const highIssuesPath = path.join(reviewFolder, "high-issues.md");
     fs.writeFileSync(highIssuesPath, highIssuesDoc, "utf-8");
 
-    const iterInfo = ` (iteration ${iterationState.current - 1}/${iterationState.max}, 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, "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);
   }
 }
 

package/dist/templates/cc-native/_cc-native/hooks/enhance_plan_post_subagent.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+/**
+ * PostToolUse:Task Hook: Plan Quality Review Context
+ *
+ * Fires after Task tool completes with a Plan subagent. Emits plan quality review guidance
+ * as context for the main agent to review the plan before ExitPlanMode.
+ *
+ * Design:
+ * - Never blocks (all errors exit 0)
+ * - Emits context via emitContext() — no file mutation
+ * - Only fires for Task tool with subagent_type="Plan"
+ */
+
+import {
+  loadHookInput,
+  runHook,
+  logInfo,
+  logDebug,
+  emitContext,
+  getToolInput,
+} from "../../_shared/lib-ts/base/hook-utils.js";
+import { isInternalCall } from "../../_shared/lib-ts/base/subprocess-utils.js";
+import { getPlanQualityReviewContext } from "../lib-ts/plan-enhancement.js";
+
+function main(): void {
+  if (isInternalCall()) return;
+
+  const payload = loadHookInput();
+  if (!payload) {
+    logDebug("enhance_plan_post_subagent", "No payload received");
+    return;
+  }
+
+  // Check if this is a Task tool call
+  if (payload.tool_name !== "Task") {
+    logDebug("enhance_plan_post_subagent", `Skipping: tool_name is "${payload.tool_name}", not "Task"`);
+    return;
+  }
+
+  // Check if the Task is spawning a Plan subagent
+  const toolInput = getToolInput(payload);
+  const subagentType = toolInput?.subagent_type;
+  logDebug("enhance_plan_post_subagent", `subagent_type: ${subagentType ?? "undefined"}`);
+
+  if (subagentType !== "Plan") {
+    logDebug("enhance_plan_post_subagent", `Skipping: subagent_type is "${subagentType}", not "Plan"`);
+    return;
+  }
+
+  logInfo("enhance_plan_post_subagent", "Emitting plan quality review context");
+  emitContext(getPlanQualityReviewContext());
+}
+
+runHook(main, "enhance_plan_post_subagent");

package/dist/templates/cc-native/_cc-native/hooks/enhance_plan_post_write.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+/**
+ * PostToolUse:Write Hook: Plan Quality Review Context
+ *
+ * Fires after Write tool completes. Detects writes to ~/.claude/plans/*.md files
+ * and emits plan quality review guidance as context.
+ *
+ * Design:
+ * - Never blocks (all paths exit 0)
+ * - Uses normalized path comparison (cross-platform)
+ * - Shares prompt logic with SubagentStop hook via plan-enhancement.ts
+ * - Emits context via emitContext() — no file mutation
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+
+import {
+  loadHookInput,
+  runHook,
+  logInfo,
+  emitContext,
+} from "../../_shared/lib-ts/base/hook-utils.js";
+import { isInternalCall } from "../../_shared/lib-ts/base/subprocess-utils.js";
+import { getPlanQualityReviewContext } from "../lib-ts/plan-enhancement.js";
+
+function main(): void {
+  if (isInternalCall()) return;
+
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  const toolInput = payload.tool_input;
+  if (!toolInput || typeof toolInput !== "object") return;
+
+  const filePath = toolInput.file_path as string | undefined;
+  if (!filePath) return;
+
+  // Normalize paths for cross-platform comparison
+  const normalizedPath = path.normalize(path.resolve(filePath));
+  const plansDir = path.normalize(path.join(os.homedir(), ".claude", "plans"));
+
+  // Check if file is a markdown file in the plans directory
+  if (!normalizedPath.startsWith(plansDir) || !normalizedPath.endsWith(".md")) {
+    return;
+  }
+
+  logInfo("enhance_plan_write", `Detected plan file write: ${filePath}`);
+  emitContext(getPlanQualityReviewContext());
+}
+
+runHook(main, "enhance_plan_post_write");

package/dist/templates/cc-native/_cc-native/hooks/mark_questions_asked.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env bun
+/**
+ * Mark Questions Asked Hook
+ *
+ * Tracks when AskUserQuestion tool is used during a session.
+ * Used by other hooks to determine if user clarification was gathered.
+ *
+ * Registered for:
+ * - PostToolUse: AskUserQuestion — marks questions asked state for this session
+ *
+ * Fail-safe: Any error exits 0 (non-blocking).
+ */
+
+import { getProjectRoot } from "../../_shared/lib-ts/base/constants.js";
+import {
+  loadHookInput,
+  runHook,
+  logInfo,
+  logDiagnostic,
+} from "../../_shared/lib-ts/base/hook-utils.js";
+import { isInternalCall } from "../../_shared/lib-ts/base/subprocess-utils.js";
+import { markQuestionsAsked } from "../lib-ts/cc-native-state.js";
+
+function main(): void {
+  // Guard: skip for internal subprocess calls (prevents recursive hook execution)
+  if (isInternalCall()) return;
+
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  const toolName = payload.tool_name;
+  const hookEvent = payload.hook_event_name ?? "unknown";
+  logDiagnostic(
+    "add_plan_context",
+    "receive",
+    `tool=${toolName}, event=${hookEvent}`,
+    { inputs: { tool_name: toolName, hook_event: hookEvent } },
+  );
+
+  const projectRoot = getProjectRoot(payload.cwd);
+
+  // PostToolUse: AskUserQuestion — mark that early questions (Phase A) were asked
+  if (toolName === "AskUserQuestion") {
+    const sessionId = String(payload.session_id ?? "");
+    if (sessionId) {
+      markQuestionsAsked(sessionId, projectRoot, "early");
+      logInfo("add_plan_context", `Marked early questions asked for session ${sessionId.slice(0, 8)}...`);
+    }
+    
+  }
+}
+
+runHook(main, "mark_questions_asked");