aiwcli 0.9.7 → 0.10.0

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

@@ -45,8 +45,10 @@ try:
     _shared = Path(__file__).parent.parent.parent / "_shared"
     sys.path.insert(0, str(_shared))
 
-    # Import subprocess utilities
+    # Import subprocess and hook utilities
     from lib.base.subprocess_utils import is_internal_call
+    from lib.base.hook_utils import emit_context, emit_context_and_block
+    from lib.base.logger import log_debug, log_info, log_warn, log_error, log_diagnostic
 
     from utils import (
         DEFAULT_DISPLAY,
@@ -54,15 +56,19 @@ try:
         REVIEW_SCHEMA,
         ReviewerResult,
         CombinedReviewResult,
-        eprint,
         project_dir,
+        eprint,
         find_plan_file,
         compute_plan_hash,
+        compute_review_decision,
         is_plan_already_reviewed,
+        was_plan_previously_denied,
         mark_plan_reviewed,
         worst_verdict,
         format_combined_markdown,
         write_combined_artifacts,
+        build_inline_review_summary,
+        extract_top_issues_text,
         load_config,
         get_display_settings,
     )
@@ -79,15 +85,23 @@ try:
         DEFAULT_COMPLEXITY_CATEGORIES,
     )
     # Import shared context system
-    from lib.context.context_manager import (
+    from lib.context.context_store import (
         get_context_by_session_id,
-        get_all_in_flight_contexts,
         get_all_contexts,
     )
     from lib.base.constants import get_context_reviews_dir, get_review_folder_path, get_context_dir
     from debug import debug_log, debug_raw
 except ImportError as e:
-    print(f"[cc-native-plan-review] Failed to import lib: {e}", file=sys.stderr)
+    try:
+        from lib.base.logger import log_error as _early_log_error
+        _early_log_error("cc-native-plan-review", f"Failed to import lib: {e}")
+    except Exception:
+        print(f"[cc-native-plan-review] Failed to import lib: {e}", file=sys.stderr)
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "additionalContext": f"[Plan Review Error] Failed to import required module: {e}. The plan review hook could not load its dependencies.",
+        }
+    }, ensure_ascii=True))
     sys.exit(0)  # Non-blocking failure
 
 # Add scripts directory to path for aggregate_agents import
@@ -99,10 +113,21 @@ try:
     from aggregate_agents import aggregate_agents
 except ImportError:
     def aggregate_agents(agents_dir: Path) -> List[Dict[str, Any]]:
-        eprint("[cc-native-plan-review] Warning: aggregate_agents not found")
+        log_warn("cc-native-plan-review", "aggregate_agents not found")
         return []
 
 
+def skip_with_info(reason: str) -> int:
+    """Exit hook with informational additionalContext instead of silently.
+
+    This ensures Claude always sees WHY the plan review was skipped,
+    making failures diagnosable instead of invisible.
+    """
+    log_info("cc-native-plan-review", f"Skipping: {reason}")
+    emit_context(f"[Plan Review Skipped] {reason}", ensure_ascii=True)
+    return 0
+
+
 # ---------------------------
 # Default Configuration
 # ---------------------------
@@ -124,7 +149,7 @@ DEFAULT_AGENT_MODEL: str = "sonnet"
 
 DEFAULT_REVIEW_ITERATIONS: Dict[str, int] = {
     "simple": 1,
-    "medium": 1,
+    "medium": 2,
     "high": 2,
 }
 
@@ -153,24 +178,26 @@ def get_active_context_for_review(session_id: str, project_root: Path) -> Option
     # Strategy 1: Find by session_id
     context = get_context_by_session_id(session_id, project_root)
     if context:
-        eprint(f"[cc-native-plan-review] Found context by session_id: {context.id}")
+        log_info("cc-native-plan-review", f"Found context by session_id: {context.id}")
         return context
 
     # Strategy 2: Single planning context (only planning mode)
-    in_flight = get_all_in_flight_contexts(project_root)
-    planning_contexts = [c for c in in_flight if c.in_flight and c.in_flight.mode == "planning"]
+    all_active = get_all_contexts(status="active", project_root=project_root)
+    # In the new system, "planning" is runtime-only (not persisted).
+    # Since this hook fires during ExitPlanMode, any active non-idle context is a candidate.
+    planning_contexts = [c for c in all_active if c.mode in ("active", "has_plan")]
     if len(planning_contexts) == 1:
-        eprint(f"[cc-native-plan-review] Found single planning context: {planning_contexts[0].id}")
+        log_info("cc-native-plan-review", f"Found single planning context: {planning_contexts[0].id}")
         return planning_contexts[0]
 
     # Multiple or no planning contexts found
     if len(planning_contexts) > 1:
-        eprint(f"[cc-native-plan-review] Multiple planning contexts ({len(planning_contexts)}), cannot determine which to use")
-    elif len(in_flight) > 0:
-        modes = [c.in_flight.mode if c.in_flight else "none" for c in in_flight]
-        eprint(f"[cc-native-plan-review] Found {len(in_flight)} in-flight context(s) with modes {modes}, but none in 'planning' mode")
+        log_warn("cc-native-plan-review", f"Multiple planning contexts ({len(planning_contexts)}), cannot determine which to use")
+    elif len(all_active) > 0:
+        modes = [c.mode for c in all_active]
+        log_info("cc-native-plan-review", f"Found {len(all_active)} active context(s) with modes {modes}, but none in 'planning' mode")
     else:
-        eprint("[cc-native-plan-review] No in-flight contexts found")
+        log_info("cc-native-plan-review", "No active contexts found")
     return None
 
 
@@ -190,7 +217,7 @@ def load_iteration_state(reviews_dir: Path) -> Optional[Dict[str, Any]]:
     try:
         return json.loads(iteration_file.read_text(encoding="utf-8"))
     except Exception as e:
-        eprint(f"[cc-native-plan-review] Failed to load iteration state: {e}")
+        log_error("cc-native-plan-review", f"Failed to load iteration state: {e}")
         return None
 
 
@@ -211,7 +238,7 @@ def save_iteration_state(reviews_dir: Path, state: Dict[str, Any]) -> bool:
         iteration_file.write_text(json.dumps(state, indent=2), encoding="utf-8")
         return True
     except Exception as e:
-        eprint(f"[cc-native-plan-review] Failed to save iteration state: {e}")
+        log_error("cc-native-plan-review", f"Failed to save iteration state: {e}")
         return False
 
 
@@ -277,14 +304,14 @@ def update_iteration_state_in_context(
 
 def should_continue_iterating_context(
     iteration: Dict[str, Any],
-    verdict: str,
+    review_score: float,
     config: Optional[Dict[str, Any]] = None,
 ) -> bool:
     """Determine if more review iterations are needed.
 
     Args:
         iteration: The iteration state dict
-        verdict: Current review verdict
+        review_score: Score from compute_review_decision (0.0 = all pass, >0 = concerns)
         config: Optional config dict with earlyExitOnAllPass setting
 
     Returns:
@@ -295,19 +322,19 @@ def should_continue_iterating_context(
 
     # At or past max iterations - no more iterations
     if current >= max_iter:
-        eprint(f"[cc-native-plan-review] At max iterations ({current}/{max_iter}), no more iterations")
+        log_info("cc-native-plan-review", f"At max iterations ({current}/{max_iter}), no more iterations")
         return False
 
     # Check early exit on all pass
-    early_exit = True
+    early_exit = False
     if config:
-        early_exit = config.get("earlyExitOnAllPass", True)
-    if early_exit and verdict == "pass":
-        eprint(f"[cc-native-plan-review] All reviewers passed and earlyExitOnAllPass=true, exiting early")
+        early_exit = config.get("earlyExitOnAllPass", False)
+    if early_exit and review_score == 0.0:
+        log_info("cc-native-plan-review", "All reviewers passed (score=0.0) and earlyExitOnAllPass=true, exiting early")
         return False
 
-    # More iterations available and verdict is not pass (or early exit disabled)
-    eprint(f"[cc-native-plan-review] Continuing to next iteration ({current + 1}/{max_iter}), verdict={verdict}")
+    # More iterations available and score is not zero (or early exit disabled)
+    log_info("cc-native-plan-review", f"Continuing to next iteration ({current + 1}/{max_iter}), score={review_score:.2f}")
     return True
 
 
@@ -324,14 +351,13 @@ def load_settings(proj_dir: Path) -> Dict[str, Any]:
                 "codex": {"enabled": True, "model": "", "timeout": 120},
                 "gemini": {"enabled": False, "model": "", "timeout": 120},
             },
-            "blockOnFail": False,
             "display": DEFAULT_DISPLAY.copy(),
         },
         "agentReview": {
             "enabled": True,
             "orchestrator": DEFAULT_ORCHESTRATOR.copy(),
             "timeout": 180,
-            "blockOnFail": True,
+            "warnThreshold": 0.5,
             "legacyMode": False,
             "display": DEFAULT_DISPLAY.copy(),
             "agentSelection": DEFAULT_AGENT_SELECTION.copy(),
@@ -375,7 +401,7 @@ def load_settings(proj_dir: Path) -> Dict[str, Any]:
 
     # Merge reviewIterations settings
     merged_agent["reviewIterations"] = {**DEFAULT_REVIEW_ITERATIONS, **agent_review.get("reviewIterations", {})}
-    merged_agent["earlyExitOnAllPass"] = agent_review.get("earlyExitOnAllPass", True)
+    merged_agent["earlyExitOnAllPass"] = agent_review.get("earlyExitOnAllPass", False)
 
     return {"planReview": merged_plan, "agentReview": merged_agent}
 
@@ -394,7 +420,7 @@ def load_agent_library(proj_dir: Path, settings: Optional[Dict[str, Any]] = None
         default_model = settings.get("agentDefaults", {}).get("model", DEFAULT_AGENT_MODEL)
 
     if not agents_data:
-        eprint("[cc-native-plan-review] No agents found in frontmatter, using defaults")
+        log_info("cc-native-plan-review", "No agents found in frontmatter, using defaults")
         return [
             AgentConfig(
                 name=a["name"],
@@ -428,25 +454,24 @@ def load_agent_library(proj_dir: Path, settings: Optional[Dict[str, Any]] = None
 # ---------------------------
 
 def main() -> int:
-    eprint("[cc-native-plan-review] Unified hook started (PreToolUse)")
+    log_info("cc-native-plan-review", "Unified hook started (PreToolUse)")
 
     # Skip if internal subprocess call (orchestrator, agents)
     if is_internal_call():
-        eprint("[cc-native-plan-review] Skipping: internal subprocess call")
+        log_debug("cc-native-plan-review", "Skipping: internal subprocess call")
         return 0
 
     try:
         payload = json.load(sys.stdin)
     except json.JSONDecodeError as e:
-        eprint(f"[cc-native-plan-review] Invalid JSON input: {e}")
-        return 0
+        return skip_with_info(f"Invalid JSON input from Claude Code: {e}")
 
     tool_name = payload.get("tool_name")
-    eprint(f"[cc-native-plan-review] tool_name: {tool_name}")
+    log_debug("cc-native-plan-review", f"tool_name: {tool_name}")
 
     # Only process ExitPlanMode
     if tool_name != "ExitPlanMode":
-        eprint("[cc-native-plan-review] Skipping: not ExitPlanMode")
+        log_debug("cc-native-plan-review", "Skipping: not ExitPlanMode")
         return 0
 
     session_id = str(payload.get("session_id", "unknown"))
@@ -460,58 +485,57 @@ def main() -> int:
     agent_review_enabled = agent_settings.get("enabled", True)
 
     if not plan_review_enabled and not agent_review_enabled:
-        eprint("[cc-native-plan-review] Skipping: both plan and agent review disabled")
+        log_info("cc-native-plan-review", "Skipping: both plan and agent review disabled")
         return 0
 
     # Find and read plan FIRST (state file is keyed by plan path)
     plan_path = find_plan_file()
     if not plan_path:
-        eprint("[cc-native-plan-review] Skipping: no plan file found in ~/.claude/plans/")
-        return 0
+        return skip_with_info("No plan file found in ~/.claude/plans/. The plan may not have been written yet.")
 
     try:
         plan = Path(plan_path).read_text(encoding="utf-8").strip()
     except Exception as e:
-        eprint(f"[cc-native-plan-review] Failed to read plan file: {e}")
-        return 0
+        return skip_with_info(f"Failed to read plan file: {e}")
 
     if not plan:
-        eprint("[cc-native-plan-review] Skipping: plan file is empty")
-        return 0
+        return skip_with_info("Plan file exists but is empty.")
 
-    eprint(f"[cc-native-plan-review] Found plan at: {plan_path}")
-    eprint(f"[cc-native-plan-review] Plan length: {len(plan)} chars")
+    log_info("cc-native-plan-review", f"Found plan at: {plan_path}")
+    log_debug("cc-native-plan-review", f"Plan length: {len(plan)} chars")
+    log_diagnostic("cc-native-plan-review", "receive", f"plan_size={len(plan)}, session={session_id[:8]}",
+                    inputs={"plan_hash": compute_plan_hash(plan), "plan_size": len(plan),
+                            "session_id": session_id[:12]})
 
     # Find active context for this review (required)
     active_context = get_active_context_for_review(session_id, base)
 
     if not active_context:
-        eprint("[cc-native-plan-review] Skipping: no active context found")
-        return 0
+        return skip_with_info("No active planning context found for this session. The context system may not have a context in 'planning' mode.")
 
     # Get base reviews dir from shared lib, then add cc-native namespace
     reviews_dir = get_context_reviews_dir(active_context.id, base) / "cc-native"
-    eprint(f"[cc-native-plan-review] Using context reviews dir: {reviews_dir}")
+    log_debug("cc-native-plan-review", f"Using context reviews dir: {reviews_dir}")
 
     # Get context path for debug logging
     context_path = get_context_dir(active_context.id, base)
-    eprint(f"[cc-native-plan-review] Context path for debug: {context_path}")
-
-    # Check if we've exhausted review iterations from context
-    existing_iteration = load_iteration_state(reviews_dir)
-    if existing_iteration:
-        current = existing_iteration.get("current", 1)
-        max_iter = existing_iteration.get("max", 1)
-        if current > max_iter:
-            eprint(f"[cc-native-plan-review] Skipping: review iterations exhausted ({current}/{max_iter})")
-            return 0
+    log_debug("cc-native-plan-review", f"Context path for debug: {context_path}")
 
-    # Plan-hash deduplication
+    # Plan-hash deduplication (decision-aware)
     plan_hash = compute_plan_hash(plan)
-    eprint(f"[cc-native-plan-review] Plan hash: {plan_hash}")
+    log_debug("cc-native-plan-review", f"Plan hash: {plan_hash}")
     if is_plan_already_reviewed(session_id, plan_hash):
-        eprint("[cc-native-plan-review] Skipping: plan already reviewed (hash match)")
-        return 0
+        if was_plan_previously_denied(session_id, plan_hash):
+            # Plan was denied and hasn't changed — block, don't re-review
+            emit_context_and_block(
+                "[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 0
+        else:
+            # Plan was reviewed and allowed — skip review, allow through
+            return skip_with_info("Plan already reviewed and approved (same hash).")
 
     # Initialize combined result
     cli_results: Dict[str, ReviewerResult] = {}
@@ -543,10 +567,16 @@ def main() -> int:
         timeout=orch_settings.get("timeout", 30),
     )
 
-    eprint(f"[cc-native-plan-review] Codex enabled: {codex_enabled}, Gemini enabled: {gemini_enabled}")
-    eprint(f"[cc-native-plan-review] Agent library: {[a.name for a in agent_library]}")
-    eprint(f"[cc-native-plan-review] Enabled agents: {[a.name for a in enabled_agents]}")
-    eprint(f"[cc-native-plan-review] Orchestrator enabled: {orchestrator_config.enabled}")
+    # Compute mandatory agent names early so orchestrator can exclude them
+    mandatory_names = set(agent_settings.get("mandatoryAgents", [
+        "handoff-readiness", "clarity-auditor", "skeptic"
+    ]))
+
+    log_debug("cc-native-plan-review", f"Codex enabled: {codex_enabled}, Gemini enabled: {gemini_enabled}")
+    log_debug("cc-native-plan-review", f"Agent library: {[a.name for a in agent_library]}")
+    log_debug("cc-native-plan-review", f"Enabled agents: {[a.name for a in enabled_agents]}")
+    log_debug("cc-native-plan-review", f"Mandatory agents: {sorted(mandatory_names)}")
+    log_debug("cc-native-plan-review", f"Orchestrator enabled: {orchestrator_config.enabled}")
 
     # Run CLI reviewers + orchestrator in parallel
     phase1_tasks = []
@@ -555,9 +585,9 @@ def main() -> int:
     if gemini_enabled:
         phase1_tasks.append(("gemini", lambda: run_gemini_review(plan, REVIEW_SCHEMA, plan_settings)))
     if orchestrator_config.enabled and enabled_agents and not legacy_mode:
-        phase1_tasks.append(("orchestrator", lambda: run_orchestrator(plan, enabled_agents, orchestrator_config, agent_settings)))
+        phase1_tasks.append(("orchestrator", lambda: run_orchestrator(plan, enabled_agents, orchestrator_config, agent_settings, mandatory_names=mandatory_names)))
 
-    eprint(f"[cc-native-plan-review] === PHASE 1: Running {len(phase1_tasks)} tasks in parallel ===")
+    log_info("cc-native-plan-review", f"=== PHASE 1: Running {len(phase1_tasks)} tasks in parallel ===")
 
     phase1_results: Dict[str, Any] = {}
     if phase1_tasks:
@@ -567,9 +597,9 @@ def main() -> int:
                 name = futures[future]
                 try:
                     phase1_results[name] = future.result()
-                    eprint(f"[cc-native-plan-review] {name} completed")
+                    log_info("cc-native-plan-review", f"{name} completed")
                 except Exception as ex:
-                    eprint(f"[cc-native-plan-review] {name} failed: {ex}")
+                    log_error("cc-native-plan-review", f"{name} failed: {ex}")
                     phase1_results[name] = None
 
     # Collect CLI results
@@ -590,14 +620,11 @@ def main() -> int:
     # PHASE 2: Agent Selection (from orchestrator result)
     # ============================================
     if agent_review_enabled:
-        eprint("[cc-native-plan-review] === PHASE 2: Agent Selection ===")
+        log_info("cc-native-plan-review", "=== PHASE 2: Agent Selection ===")
 
         selected_agents: List[AgentConfig] = []
 
-        # Load mandatory and fallback config
-        mandatory_names = set(agent_settings.get("mandatoryAgents", [
-            "handoff-readiness", "clarity-auditor", "skeptic"
-        ]))
+        # Load fallback config (mandatory_names already computed above)
         fallback_by_complexity = agent_settings.get("fallbackByComplexity", {
             "simple": 0, "medium": 5, "high": 9
         })
@@ -607,8 +634,8 @@ def main() -> int:
             mandatory_agents = [a for a in enabled_agents if a.name in mandatory_names]
             non_mandatory = [a for a in enabled_agents if a.name not in mandatory_names]
 
-            eprint(f"[cc-native-plan-review] Mandatory agents: {[a.name for a in mandatory_agents]}")
-            eprint(f"[cc-native-plan-review] Non-mandatory pool: {len(non_mandatory)} agents")
+            log_debug("cc-native-plan-review", f"Mandatory agents: {[a.name for a in mandatory_agents]}")
+            log_debug("cc-native-plan-review", f"Non-mandatory pool: {len(non_mandatory)} agents")
 
             if orch_result and not legacy_mode:
                 detected_complexity = orch_result.complexity
@@ -617,35 +644,50 @@ def main() -> int:
                 orch_selected_names = set(orch_result.selected_agents) - mandatory_names
                 orch_selected = [a for a in non_mandatory if a.name in orch_selected_names]
 
-                eprint(f"[cc-native-plan-review] Orchestrator selected (non-mandatory): {[a.name for a in orch_selected]}")
+                log_debug("cc-native-plan-review", f"Orchestrator selected (non-mandatory): {[a.name for a in orch_selected]}")
+
+                # Diagnostic: warn if orchestrator returned names not in our agent pool
+                unmatched = orch_selected_names - {a.name for a in non_mandatory}
+                if unmatched:
+                    log_warn("cc-native-plan-review", f"Orchestrator selected unknown agents: {unmatched}")
 
-                # Random fallback if orchestrator selected zero additional agents
-                if not orch_selected and non_mandatory:
-                    fallback_count = fallback_by_complexity.get(detected_complexity, 5)
-                    fallback_count = min(fallback_count, len(non_mandatory))
-                    if fallback_count > 0:
-                        orch_selected = random.sample(non_mandatory, fallback_count)
-                        eprint(f"[cc-native-plan-review] Random fallback ({detected_complexity}): {[a.name for a in orch_selected]}")
+                # Enforce minimum agent count — top up with random agents if orchestrator selected too few
+                min_additional = fallback_by_complexity.get(detected_complexity, 5)
+                if len(orch_selected) < min_additional and non_mandatory:
+                    remaining = [a for a in non_mandatory if a not in orch_selected]
+                    top_up_count = min(min_additional - len(orch_selected), len(remaining))
+                    if top_up_count > 0:
+                        top_up = random.sample(remaining, top_up_count)
+                        orch_selected.extend(top_up)
+                        log_debug("cc-native-plan-review", f"Topped up {top_up_count} agents to meet {detected_complexity} minimum: {[a.name for a in top_up]}")
 
                 # Combine: mandatory + orchestrator/fallback selection
                 selected_agents = mandatory_agents + orch_selected
-                eprint(f"[cc-native-plan-review] Final selection: {len(selected_agents)} agents ({len(mandatory_agents)} mandatory + {len(orch_selected)} additional)")
+                log_info("cc-native-plan-review", f"Final selection: {len(selected_agents)} agents ({len(mandatory_agents)} mandatory + {len(orch_selected)} additional)")
             else:
-                eprint("[cc-native-plan-review] Running in legacy mode (all enabled agents)")
+                log_info("cc-native-plan-review", "Running in legacy mode (all enabled agents)")
                 selected_agents = enabled_agents
                 detected_complexity = "medium"  # Default for legacy mode
 
+        log_diagnostic("cc-native-plan-review", "decide",
+                        f"Selected {len(selected_agents)} agents, complexity={detected_complexity}",
+                        decision="agents_selected",
+                        reasoning=f"orchestrator={orch_result is not None}, legacy={legacy_mode}",
+                        inputs={"agents": [a.name for a in selected_agents],
+                                "complexity": detected_complexity,
+                                "mandatory_count": len([a for a in selected_agents if a.name in mandatory_names])})
+
         # Initialize iteration state based on complexity (after orchestrator runs)
         if reviews_dir:
             iteration_state = get_iteration_state_from_context(reviews_dir, detected_complexity, agent_settings)
-            eprint(f"[cc-native-plan-review] Iteration state: {iteration_state['current']}/{iteration_state['max']} ({detected_complexity})")
+            log_debug("cc-native-plan-review", f"Iteration state: {iteration_state['current']}/{iteration_state['max']} ({detected_complexity})")
 
         # PHASE 3: Run selected agents in parallel
         if selected_agents:
-            eprint("[cc-native-plan-review] === PHASE 3: Agent Reviews ===")
+            log_info("cc-native-plan-review", "=== PHASE 3: Agent Reviews ===")
             max_parallel = agent_settings.get("maxParallelAgents", 0)  # 0 = unlimited
             num_workers = len(selected_agents) if max_parallel <= 0 else min(max_parallel, len(selected_agents))
-            eprint(f"[cc-native-plan-review] Launching {len(selected_agents)} agents in parallel (workers={num_workers})")
+            log_info("cc-native-plan-review", f"Launching {len(selected_agents)} agents in parallel (workers={num_workers})")
 
             # Debug log the agent review start
             debug_log(context_path, session_id, "hook", "agent_review_start", {
@@ -666,9 +708,9 @@ def main() -> int:
                         agent_results[agent.name] = result
                         if result.verdict and result.verdict not in ("skip", "error"):
                             all_verdicts.append(result.verdict)
-                        eprint(f"[cc-native-plan-review] {agent.name} completed with verdict: {result.verdict}")
+                        log_info("cc-native-plan-review", f"{agent.name} completed with verdict: {result.verdict}")
                     except Exception as ex:
-                        eprint(f"[cc-native-plan-review] {agent.name} failed with exception: {ex}")
+                        log_error("cc-native-plan-review", f"{agent.name} failed with exception: {ex}")
                         agent_results[agent.name] = ReviewerResult(
                             name=agent.name,
                             ok=False,
@@ -681,11 +723,10 @@ def main() -> int:
     # ============================================
     # PHASE 4: Generate Combined Output
     # ============================================
-    eprint("[cc-native-plan-review] === PHASE 4: Generate Output ===")
+    log_info("cc-native-plan-review", "=== PHASE 4: Generate Output ===")
 
     if not cli_results and not agent_results:
-        eprint("[cc-native-plan-review] No review results, exiting")
-        return 0
+        return skip_with_info("All reviewers failed to produce results. Check stderr logs for details.")
 
     overall = worst_verdict(all_verdicts) if all_verdicts else "pass"
 
@@ -710,37 +751,47 @@ def main() -> int:
     # Create review folder with datetime and iteration in name
     review_folder = get_review_folder_path(active_context.id, current_iteration, base)
     review_folder.mkdir(parents=True, exist_ok=True)
-    eprint(f"[cc-native-plan-review] Created review folder: {review_folder}")
+    log_info("cc-native-plan-review", f"Created review folder: {review_folder}")
 
     review_file = write_combined_artifacts(
         base, plan, combined_result, payload, combined_settings,
         review_folder=review_folder,
         iteration=current_iteration,
     )
-    eprint(f"[cc-native-plan-review] Saved review: {review_file}")
+    log_info("cc-native-plan-review", f"Saved review: {review_file}")
 
-    # Build context message
-    md_content = format_combined_markdown(combined_result, combined_settings)
+    # Build inline review summary for additionalContext
+    inline_summary = build_inline_review_summary(combined_result)
 
-    context_parts = [
-        "**CC-Native Plan Review Complete**\n\n",
-        f"Review saved to: `{review_file}`\n\n",
-    ]
+    context_parts = [inline_summary, f"\nFull review: `{review_file}`\n"]
 
-    if cli_results:
-        cli_verdicts = [f"{name}={r.verdict}" for name, r in cli_results.items()]
-        context_parts.append(f"**CLI Reviewers:** {', '.join(cli_verdicts)}\n")
+    # Review decision — only fail triggers a block
+    warn_threshold = agent_settings.get("warnThreshold", 0.5)
+    should_deny, deny_reason, review_score = compute_review_decision(all_verdicts, warn_threshold)
 
-    if orch_result:
-        context_parts.append(f"**Orchestration:** Complexity=`{orch_result.complexity}`, Category=`{orch_result.category}`, Agents selected: {len(agent_results)}\n")
-
-    context_parts.append("\nUse these findings before starting implementation.\n\n")
-    context_parts.append(md_content)
+    # Count high-severity issues for logging
+    high_count = sum(
+        1 for r in list(combined_result.cli_reviewers.values()) + list(combined_result.agents.values())
+        if r.data
+        for issue in r.data.get("issues", [])
+        if issue.get("severity") == "high"
+    )
 
-    # Check blocking conditions
-    block_on_fail_plan = plan_settings.get("blockOnFail", False)
-    block_on_fail_agent = agent_settings.get("blockOnFail", True)
-    should_block = (overall == "fail") and (block_on_fail_plan or block_on_fail_agent)
+    # Structured log entries for review influence tracking
+    log_info("cc-native-plan-review", f"REVIEW_DECISION: verdict={combined_result.overall_verdict}, deny={should_deny}, score={review_score:.2f}, high_issues={high_count}")
+    log_diagnostic("cc-native-plan-review", "result",
+                    f"verdict={combined_result.overall_verdict}, deny={should_deny}, high={high_count}",
+                    decision="deny" if should_deny else "allow",
+                    reasoning=f"score={review_score:.2f}, threshold={warn_threshold}",
+                    inputs={"overall_verdict": combined_result.overall_verdict,
+                            "high_issue_count": high_count, "review_score": round(review_score, 2),
+                            "cli_count": len(cli_results), "agent_count": len(agent_results)})
+
+    # Terminal progress indicator
+    verdict_emoji = "✅" if not should_deny else "❌"
+    eprint(f"[plan-review] {verdict_emoji} {combined_result.overall_verdict.upper()} (score={review_score:.2f})")
+    if should_deny:
+        eprint(f"[plan-review] Blocking ExitPlanMode — {high_count} high-severity issue(s) found")
 
     # Handle iteration logic
     needs_more_iterations = False
@@ -749,7 +800,7 @@ def main() -> int:
         iteration_state = update_iteration_state_in_context(reviews_dir, iteration_state, plan_hash, overall)
 
         # Check if more iterations needed
-        if should_continue_iterating_context(iteration_state, overall, agent_settings):
+        if should_continue_iterating_context(iteration_state, review_score, agent_settings):
             needs_more_iterations = True
             # Increment iteration counter for next round
             iteration_state["current"] = iteration_state.get("current", 1) + 1
@@ -760,60 +811,59 @@ def main() -> int:
             iteration_state["current"] = iteration_state.get("current", 1) + 1
             # Also increment max by 1 to allow another review cycle if the user rejects
             # the plan and requests changes. Without this, once iterations are exhausted,
-            # the hook would skip review entirely (line ~498) even if the user sent the
+            # the hook would skip review entirely even if the user sent the
             # planner back to revise. This ensures rejected plans can always be re-reviewed.
             iteration_state["max"] = iteration_state.get("max", 1) + 1
             save_iteration_state(reviews_dir, iteration_state)
 
-    # Build output with correct Claude Code hook format
-    # See: https://docs.anthropic.com/en/docs/claude-code/hooks
-    out: Dict[str, Any] = {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "additionalContext": "".join(context_parts),
-        }
-    }
+    # Emit output with correct Claude Code hook format
+    context_text = "".join(context_parts)
+
+    log_debug("cc-native-plan-review", f"REVIEW_CONTEXT_INJECTED: chars={len(context_text)}, inline_chars={len(inline_summary)}")
+
+    _REVIEWER_CAVEAT = (
+        "Reviewers have limited context compared to your full session — "
+        "adopt valid points, use your judgment where they lack context."
+    )
+
+    _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."
+    )
 
-    # Handle blocking scenarios - use permissionDecision/permissionDecisionReason inside hookSpecificOutput
-    # Note: md_content is already in additionalContext, so permissionDecisionReason only needs the instruction
     if needs_more_iterations:
+        mark_plan_reviewed(session_id, plan_hash, "cc-native-plan-review", iteration_state, decision="deny")
         current = iteration_state["current"] - 1  # Display the just-completed iteration
         max_iter = iteration_state["max"]
         remaining = max_iter - current
-
-        out["hookSpecificOutput"]["permissionDecision"] = "deny"
-        out["hookSpecificOutput"]["permissionDecisionReason"] = (
-            f"CC-Native plan review iteration {current}/{max_iter} verdict = {overall.upper()}. "
-            f"REVISION REQUIRED: Address the issues in additionalContext. "
-            f"Revise the plan in place, then attempt ExitPlanMode again. "
-            f"({remaining} revision{'s' if remaining != 1 else ''} remaining)"
+        top_issues_text = extract_top_issues_text(combined_result, max_count=3, severity="high")
+        emit_context_and_block(
+            context_text,
+            f"Plan review iteration {current}/{max_iter} FAILED ({deny_reason}, score={review_score:.2f}). "
+            f"Critical issues: {top_issues_text}. "
+            f"{_REVIEWER_CAVEAT} "
+            f"Revise the plan, then call ExitPlanMode again. "
+            f"({remaining} revision{'s' if remaining != 1 else ''} remaining) "
+            f"{_RESUBMIT_INSTRUCTION}",
         )
-    elif should_block:
-        out["hookSpecificOutput"]["permissionDecision"] = "deny"
-        out["hookSpecificOutput"]["permissionDecisionReason"] = (
-            "CC-Native plan review verdict = FAIL. Do NOT start implementation yet. "
-            "Revise the plan to address the issues in additionalContext, "
-            "then attempt ExitPlanMode again."
+    elif should_deny:
+        mark_plan_reviewed(session_id, plan_hash, "cc-native-plan-review", iteration_state, decision="deny")
+        top_issues_text = extract_top_issues_text(combined_result, max_count=3, severity="high")
+        emit_context_and_block(
+            context_text,
+            f"Plan review FAILED ({deny_reason}, score={review_score:.2f}). "
+            f"Critical issues: {top_issues_text}. "
+            f"{_REVIEWER_CAVEAT} "
+            f"Revise the plan, then call ExitPlanMode again. "
+            f"{_RESUBMIT_INSTRUCTION}",
         )
+    else:
+        mark_plan_reviewed(session_id, plan_hash, "cc-native-plan-review", iteration_state, decision="allow")
+        emit_context(context_text, ensure_ascii=True)
 
-    mark_plan_reviewed(session_id, plan_hash, "cc-native-plan-review", iteration_state)
-    # Use ensure_ascii=True to avoid Windows cp1252 encoding errors
-    print(json.dumps(out, ensure_ascii=True))
     return 0
 
 
 if __name__ == "__main__":
-    try:
-        raise SystemExit(main())
-    except Exception as e:
-        import traceback
-        print(f"[cc-native-plan-review] FATAL ERROR: {e}", file=sys.stderr)
-        traceback.print_exc(file=sys.stderr)
-        # Output error to Claude via hook format so it's visible
-        print(json.dumps({
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "additionalContext": f"**CC-Native Plan Review Hook Error**\n\nThe hook encountered an error:\n```\n{traceback.format_exc()}\n```\n\nPlease report this issue.",
-            }
-        }))
-        raise SystemExit(1)
+    from base.hook_utils import run_hook
+    run_hook(main, "cc_native_plan_review")