avorelo 0.1.0

package/scripts/lib/lifecycle-hooks.js

@@ -0,0 +1,802 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const CONTRACT = "avorelo.lifecycleHookHandler.v1";
+const SCHEMA_VERSION = 1;
+
+const HOOKS_DIR_REL = ".claude/cco/orchestration/lifecycle-hooks";
+
+const DESTRUCTIVE_KEYWORDS = Object.freeze([
+  "deploy",
+  "publish",
+  "delete database",
+  "drop table",
+  "rm -rf",
+  "git clean",
+  "force push",
+  "reset --hard",
+  "secret",
+  "password",
+  "api key",
+  "prod",
+  "production",
+  "staging push",
+]);
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function makeHandlerId() {
+  return `lh-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function safeWriteJson(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function containsDestructiveIntent(text) {
+  if (!text) return false;
+  const lower = text.toLowerCase();
+  return DESTRUCTIVE_KEYWORDS.some((kw) => lower.includes(kw));
+}
+
+function writeReceipt(cwd, event, result) {
+  const eventSlug = event.toLowerCase().replace(/[^a-z0-9]/g, "-");
+  const relPath = `${HOOKS_DIR_REL}/latest-${eventSlug}.json`;
+  const absPath = path.join(cwd, relPath);
+  safeWriteJson(absPath, result);
+  return relPath;
+}
+
+function writeLedgerEntry(cwd, event, result) {
+  try {
+    const { appendProductLearningEvent } = require("./product-learning-events");
+    appendProductLearningEvent(cwd, {
+      eventName: "lifecycle_hook_handler_invoked",
+      payload: {
+        event,
+        handlerId: result.handlerId,
+        status: result.status,
+        blocking: result.blocking,
+        reasonCodes: result.reasonCodes || [],
+      },
+    });
+  } catch {
+    // product-learning not available — non-fatal
+  }
+}
+
+// ── SessionStart ─────────────────────────────────────────────────────────────
+
+function handleSessionStart(cwd, input = {}, options = {}) {
+  const handlerId = makeHandlerId();
+  const result = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    handlerId,
+    event: "SessionStart",
+    blocking: false,
+    status: "ok",
+    createdAt: nowIso(),
+    actions: [],
+    summary: null,
+    redacted: true,
+  };
+
+  // Load project profile (cheap, local)
+  try {
+    const profilePath = path.join(cwd, ".claude/cco/orchestration/project-profile/latest-profile.json");
+    const profile = safeReadJson(profilePath);
+    if (profile) {
+      result.actions.push({ action: "project_profile_loaded", status: "ok" });
+      result.projectProfile = {
+        framework: profile.framework || null,
+        packageManager: profile.packageManager || null,
+        allowedActions: profile.allowedActions ? profile.allowedActions.slice(0, 5) : [],
+        redacted: true,
+      };
+    } else {
+      result.actions.push({ action: "project_profile_loaded", status: "not_found" });
+    }
+  } catch {
+    result.actions.push({ action: "project_profile_loaded", status: "error" });
+  }
+
+  // Workspace hygiene summary (status only, no heavy scan)
+  try {
+    const hygienePath = path.join(cwd, ".claude/cco/orchestration/ai-workspace-hygiene/latest-report.json");
+    const hygiene = safeReadJson(hygienePath);
+    if (hygiene) {
+      result.actions.push({ action: "workspace_hygiene_checked", status: "ok" });
+      result.workspaceStatus = {
+        status: hygiene.status || "unknown",
+        redacted: true,
+      };
+    } else {
+      result.actions.push({ action: "workspace_hygiene_checked", status: "not_found" });
+    }
+  } catch {
+    result.actions.push({ action: "workspace_hygiene_checked", status: "skipped" });
+  }
+
+  // Auto-inject next-run context if available and not expired
+  try {
+    const { loadNextRunContext, buildCompactContextText, updateNextRunContextStatus, emitNextRunContextEvent } = require("./next-run-context");
+    const nrc = loadNextRunContext(cwd);
+    if (nrc && nrc.status !== "not_available" && nrc.status !== "expired" && nrc.status !== "insufficient_evidence" && nrc.status !== "error") {
+      const compactText = buildCompactContextText(nrc);
+      result.actions.push({ action: "next_run_context_loaded", status: "ok" });
+      result.nextRunContext = {
+        status: nrc.status,
+        defaultsCount: (nrc.appliedDefaults || []).length,
+        decisionsCount: nrc.activeDecisionCount || 0,
+        risksCount: nrc.activeRiskCount || 0,
+        sourceRunFingerprint: nrc.sourceRunFingerprint,
+        compactText: compactText || null,
+        artifactPath: ".claude/cco/state/next-run-context.json",
+        redacted: true,
+      };
+      // Mark as injected if it was applied (session-start is the real injection point)
+      if (nrc.status === "applied") {
+        const now = nowIso();
+        updateNextRunContextStatus(cwd, "injected", { injectedAt: now });
+        emitNextRunContextEvent(cwd, { ...nrc, status: "injected", injectedSurface: "session_start" }, "next_run_context.injected");
+        result.nextRunContext.status = "injected";
+      }
+    } else {
+      result.actions.push({ action: "next_run_context_loaded", status: nrc ? nrc.status : "not_found" });
+    }
+  } catch {
+    result.actions.push({ action: "next_run_context_loaded", status: "skipped" });
+  }
+
+  result.summary = "Session state prepared. Project profile, workspace status, and next-run context loaded.";
+  result.safeNextAction = "Continue session. Avorelo has prepared project/workspace state.";
+  result.reasonCodes = ["SESSION_STATE_PREPARED", "NON_BLOCKING"];
+
+  const receiptPath = writeReceipt(cwd, "SessionStart", result);
+  result.receiptPath = receiptPath;
+  writeLedgerEntry(cwd, "SessionStart", result);
+
+  return result;
+}
+
+// ── UserPromptSubmit ──────────────────────────────────────────────────────────
+
+function handleUserPromptSubmit(cwd, input = {}, options = {}) {
+  const handlerId = makeHandlerId();
+  const taskText = input.prompt || input.taskText || input.task || "";
+
+  const result = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    handlerId,
+    event: "UserPromptSubmit",
+    blocking: false,
+    status: "ok",
+    createdAt: nowIso(),
+    actions: [],
+    decision: "allow",
+    summary: null,
+    redacted: true,
+  };
+
+  // Check for prohibited intent
+  if (containsDestructiveIntent(taskText)) {
+    result.blocking = true;
+    result.decision = "block";
+    result.status = "blocked";
+    result.summary = "Prompt contains prohibited intent (destructive/deploy/secrets/prod). Blocked before routing.";
+    result.safeNextAction = "Rephrase the task to avoid destructive, deployment, or secrets-related actions.";
+    result.reasonCodes = ["BLOCKING_PROHIBITED_INTENT", "DESTRUCTIVE_KEYWORDS_DETECTED"];
+    result.actions.push({ action: "prompt_classified", status: "blocked", reason: "prohibited_intent" });
+    const receiptPath = writeReceipt(cwd, "UserPromptSubmit", result);
+    result.receiptPath = receiptPath;
+    writeLedgerEntry(cwd, "UserPromptSubmit", result);
+    try {
+      const { appendProductLearningEvent } = require("./product-learning-events");
+      appendProductLearningEvent(cwd, {
+        eventName: "lifecycle_pre_tool_use_blocked",
+        payload: { event: "UserPromptSubmit", reason: "prohibited_intent", redacted: true },
+      });
+    } catch {}
+    return result;
+  }
+
+  result.actions.push({ action: "prompt_classified", status: "ok", reason: "safe" });
+
+  // Build safe-run plan (prepare-only, no execution)
+  if (taskText) {
+    try {
+      const { buildSafeRunPlan } = require("./safe-run-controller");
+      const plan = buildSafeRunPlan(cwd, taskText, { prepareOnly: true });
+      result.actions.push({ action: "safe_run_plan_built", status: "ok" });
+      result.safeRunPlan = {
+        runId: plan.runId || null,
+        taskType: plan.taskType || null,
+        riskLevel: plan.riskLevel || null,
+        steps: plan.steps ? plan.steps.length : 0,
+        redacted: true,
+      };
+    } catch {
+      result.actions.push({ action: "safe_run_plan_built", status: "skipped" });
+    }
+
+    // Smart-route
+    try {
+      const { classifyTaskForRouting, decideExecutionPath } = require("./smart-work-routing");
+      const classification = classifyTaskForRouting(taskText);
+      result.actions.push({ action: "smart_route_classified", status: "ok" });
+      result.routeClassification = {
+        taskType: classification.taskType || null,
+        riskLevel: classification.riskLevel || null,
+        redacted: true,
+      };
+    } catch {
+      result.actions.push({ action: "smart_route_classified", status: "skipped" });
+    }
+
+    // Compile execution packet (prepare only)
+    try {
+      const { compileExecutionPacket } = require("./execution-packet");
+      if (typeof compileExecutionPacket === "function") {
+        const packet = compileExecutionPacket(cwd, { task: taskText, prepareOnly: true });
+        result.actions.push({ action: "execution_packet_compiled", status: "ok" });
+        result.executionPacket = {
+          packetId: packet.packetId || null,
+          mode: packet.mode || null,
+          riskLevel: packet.riskLevel || null,
+          redacted: true,
+        };
+      }
+    } catch {
+      result.actions.push({ action: "execution_packet_compiled", status: "skipped" });
+    }
+  }
+
+  result.summary = "Task classified and safe run plan prepared. No code modified.";
+  result.safeNextAction = "Continue with the prepared execution plan.";
+  result.reasonCodes = ["NON_BLOCKING", "TASK_CLASSIFIED", "SAFE_RUN_PLAN_PREPARED"];
+
+  const receiptPath = writeReceipt(cwd, "UserPromptSubmit", result);
+  result.receiptPath = receiptPath;
+  writeLedgerEntry(cwd, "UserPromptSubmit", result);
+
+  return result;
+}
+
+// ── PreToolUse ────────────────────────────────────────────────────────────────
+
+const BLOCKED_TOOL_PATTERNS = Object.freeze([
+  /deploy/i,
+  /publish/i,
+  /drop[_\s]table/i,
+  /delete[_\s]database/i,
+  /rm\s+-rf/i,
+  /git\s+clean/i,
+  /force[_\s]push/i,
+  /reset\s+--hard/i,
+]);
+
+const BLOCKED_INPUT_PATTERNS = Object.freeze([
+  { key: "command", patterns: [/deploy/i, /publish/i, /rm\s+-rf/i, /git\s+clean/i, /reset\s+--hard/i, /force.*push/i] },
+  { key: "file_path", patterns: [/\.env$/, /\.pem$/, /\.key$/, /secrets?\./i] },
+  { key: "path", patterns: [/\.env$/, /\.pem$/, /\.key$/, /secrets?\./i] },
+]);
+
+function evaluateToolSafety(toolName, toolInput) {
+  const toolStr = String(toolName || "").toLowerCase();
+
+  // Check tool name for blocked patterns
+  for (const pat of BLOCKED_TOOL_PATTERNS) {
+    if (pat.test(toolStr)) {
+      return {
+        decision: "block",
+        reason: `Tool name matches blocked pattern: ${pat}`,
+        reasonCode: "TOOL_NAME_BLOCKED",
+      };
+    }
+  }
+
+  // Check input fields
+  const inputObj = typeof toolInput === "object" && toolInput !== null ? toolInput : {};
+  for (const { key, patterns } of BLOCKED_INPUT_PATTERNS) {
+    const val = String(inputObj[key] || "");
+    if (!val) continue;
+    for (const pat of patterns) {
+      if (pat.test(val)) {
+        return {
+          decision: "block",
+          reason: `Input field '${key}' matches blocked pattern`,
+          reasonCode: "INPUT_FIELD_BLOCKED",
+        };
+      }
+    }
+  }
+
+  // Check for secrets in input values
+  const inputStr = JSON.stringify(inputObj).toLowerCase();
+  if (/password|api_key|apikey|secret|token/.test(inputStr)) {
+    return {
+      decision: "warn",
+      reason: "Input may reference sensitive fields (secrets/tokens). Review before proceeding.",
+      reasonCode: "SENSITIVE_INPUT_DETECTED",
+    };
+  }
+
+  return { decision: "allow", reason: "Tool and input appear safe.", reasonCode: "SAFE_TOOL_INPUT" };
+}
+
+function handlePreToolUse(cwd, input = {}, options = {}) {
+  const handlerId = makeHandlerId();
+  const toolName = input.tool_name || input.toolName || input.tool || "";
+  const toolInput = input.tool_input || input.toolInput || input.input || {};
+
+  const result = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    handlerId,
+    event: "PreToolUse",
+    blocking: true,
+    status: "ok",
+    createdAt: nowIso(),
+    actions: [],
+    decision: "allow",
+    toolName,
+    summary: null,
+    redacted: true,
+  };
+
+  const safety = evaluateToolSafety(toolName, toolInput);
+  result.actions.push({ action: "tool_safety_evaluated", status: safety.decision, reason: safety.reason });
+  result.decision = safety.decision;
+  result.reasonCode = safety.reasonCode;
+
+  // MCP governance: apply least-privilege policy if tool signal present
+  if (result.decision !== "block") {
+    try {
+      const { decideMcpPreToolUse, writeMcpPreToolUseDecision } = require("./mcp-enforcement");
+      const mcpDecision = decideMcpPreToolUse(cwd, input, options);
+      writeMcpPreToolUseDecision(cwd, mcpDecision);
+      result.actions.push({ action: "mcp_governance_evaluated", status: mcpDecision.decision });
+      if (mcpDecision.decision === "block" || mcpDecision.decision === "approval_required") {
+        if (result.decision !== "block") {
+          result.decision = mcpDecision.decision === "block" ? "block" : "warn";
+          result.reasonCode = "MCP_GOVERNANCE_DECISION";
+          result.mcpGovernance = {
+            decision: mcpDecision.decision,
+            reasonCodes: (mcpDecision.reasonCodes || []).slice(0, 5),
+            safeNextAction: mcpDecision.safeNextAction,
+          };
+        }
+      }
+    } catch {
+      result.actions.push({ action: "mcp_governance_evaluated", status: "skipped" });
+    }
+  }
+
+  if (result.decision === "block") {
+    result.status = "blocked";
+    result.summary = `Tool use blocked: ${safety.reason}`;
+    result.safeNextAction = result.mcpGovernance?.safeNextAction || "Use a safe, whitelisted tool. Avoid destructive/deploy/secrets/prod actions.";
+    result.reasonCodes = ["BLOCKING_HOOK", "DESTRUCTIVE_OR_SENSITIVE_BLOCKED", safety.reasonCode];
+
+    try {
+      const { appendProductLearningEvent } = require("./product-learning-events");
+      appendProductLearningEvent(cwd, {
+        eventName: "lifecycle_pre_tool_use_blocked",
+        payload: { event: "PreToolUse", toolName, reasonCode: safety.reasonCode, redacted: true },
+      });
+    } catch {}
+  } else if (safety.decision === "warn") {
+    result.status = "warn";
+    result.summary = `Tool use allowed with warning: ${safety.reason}`;
+    result.safeNextAction = "Proceed with caution. Verify input does not contain secrets or sensitive data.";
+    result.reasonCodes = ["BLOCKING_HOOK", "ALLOWED_WITH_WARNING", safety.reasonCode];
+  } else {
+    result.status = "ok";
+    result.summary = "Tool use allowed.";
+    result.safeNextAction = null;
+    result.reasonCodes = ["BLOCKING_HOOK", "ALLOWED", safety.reasonCode];
+  }
+
+  // Enforce packet boundaries if packet exists
+  try {
+    const packetPath = path.join(cwd, ".claude/cco/orchestration/execution-packet/latest-packet.json");
+    const packet = safeReadJson(packetPath);
+    if (packet && packet.blockedScope && Array.isArray(packet.blockedScope)) {
+      const toolLower = toolName.toLowerCase();
+      const blocked = packet.blockedScope.some((s) => toolLower.includes(String(s).toLowerCase()));
+      if (blocked && result.decision !== "block") {
+        result.decision = "block";
+        result.status = "blocked";
+        result.summary = `Tool '${toolName}' is in the blocked scope of the current execution packet.`;
+        result.safeNextAction = "Review the execution packet blocked scope. This action is not allowed for the current task.";
+        result.reasonCodes = ["BLOCKING_HOOK", "PACKET_BOUNDARY_ENFORCED"];
+        result.actions.push({ action: "packet_boundary_checked", status: "blocked", reason: "in_blocked_scope" });
+      } else {
+        result.actions.push({ action: "packet_boundary_checked", status: "ok" });
+      }
+    } else {
+      result.actions.push({ action: "packet_boundary_checked", status: "no_packet" });
+    }
+  } catch {
+    result.actions.push({ action: "packet_boundary_checked", status: "skipped" });
+  }
+
+  const receiptPath = writeReceipt(cwd, "PreToolUse", result);
+  result.receiptPath = receiptPath;
+  writeLedgerEntry(cwd, "PreToolUse", result);
+
+  return result;
+}
+
+// ── PostToolUse ───────────────────────────────────────────────────────────────
+
+function handlePostToolUse(cwd, input = {}, options = {}) {
+  const handlerId = makeHandlerId();
+  const toolName = input.tool_name || input.toolName || input.tool || "";
+
+  const result = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    handlerId,
+    event: "PostToolUse",
+    blocking: false,
+    status: "ok",
+    createdAt: nowIso(),
+    actions: [],
+    summary: null,
+    redacted: true,
+  };
+
+  // Record tool result summary (no raw output)
+  result.actions.push({
+    action: "tool_result_recorded",
+    status: "ok",
+    toolName,
+    note: "Raw tool output not stored. Status and metadata only.",
+  });
+
+  // Write product-learning event
+  try {
+    const { appendProductLearningEvent } = require("./product-learning-events");
+    appendProductLearningEvent(cwd, {
+      eventName: "lifecycle_hook_handler_invoked",
+      payload: {
+        event: "PostToolUse",
+        handlerId,
+        toolName,
+        status: "ok",
+        redacted: true,
+      },
+    });
+    result.actions.push({ action: "product_learning_event_written", status: "ok" });
+  } catch {
+    result.actions.push({ action: "product_learning_event_written", status: "skipped" });
+  }
+
+  result.summary = `Tool '${toolName}' post-use recorded. Ledger and product-learning updated.`;
+  result.safeNextAction = null;
+  result.reasonCodes = ["NON_BLOCKING", "LEDGER_UPDATED", "PRODUCT_LEARNING_RECORDED"];
+
+  const receiptPath = writeReceipt(cwd, "PostToolUse", result);
+  result.receiptPath = receiptPath;
+  writeLedgerEntry(cwd, "PostToolUse", result);
+
+  return result;
+}
+
+// ── Stop ─────────────────────────────────────────────────────────────────────
+
+function handleStop(cwd, input = {}, options = {}) {
+  const handlerId = makeHandlerId();
+
+  const result = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    handlerId,
+    event: "Stop",
+    blocking: true,
+    status: "ok",
+    createdAt: nowIso(),
+    actions: [],
+    decision: "allow",
+    proofRequired: false,
+    proofFound: false,
+    summary: null,
+    redacted: true,
+  };
+
+  // Check execution packet for proof requirements
+  let proofRequired = false;
+  try {
+    const packetPath = path.join(cwd, ".claude/cco/orchestration/execution-packet/latest-packet.json");
+    const packet = safeReadJson(packetPath);
+    if (packet) {
+      proofRequired = !!(packet.proofRequired || (packet.requirements && packet.requirements.proofRequired));
+      result.actions.push({ action: "execution_packet_checked", status: "ok", proofRequired });
+    } else {
+      result.actions.push({ action: "execution_packet_checked", status: "not_found" });
+    }
+  } catch {
+    result.actions.push({ action: "execution_packet_checked", status: "skipped" });
+  }
+
+  // Check safe-run result for proof
+  let proofFound = false;
+  try {
+    const runPath = path.join(cwd, ".claude/cco/orchestration/safe-run/latest-run.json");
+    const run = safeReadJson(runPath);
+    if (run) {
+      proofFound = !!(run.proofSummary || run.status === "completed" || run.proofGenerated);
+      result.actions.push({ action: "safe_run_checked", status: "ok", proofFound });
+    } else {
+      result.actions.push({ action: "safe_run_checked", status: "not_found" });
+    }
+  } catch {
+    result.actions.push({ action: "safe_run_checked", status: "skipped" });
+  }
+
+  result.proofRequired = proofRequired;
+  result.proofFound = proofFound;
+
+  if (proofRequired && !proofFound) {
+    result.decision = "block";
+    result.status = "blocked";
+    result.summary = "Proof required by execution packet but not found. Cannot stop until proof is generated.";
+    result.safeNextAction = "Run `avorelo run <task>` to generate proof, then stop.";
+    result.reasonCodes = ["BLOCKING_HOOK", "PROOF_REQUIRED", "PROOF_MISSING"];
+
+    try {
+      const { appendProductLearningEvent } = require("./product-learning-events");
+      appendProductLearningEvent(cwd, {
+        eventName: "lifecycle_stop_proof_required",
+        payload: { event: "Stop", proofRequired, proofFound, redacted: true },
+      });
+    } catch {}
+  } else {
+    result.decision = "allow";
+    result.status = "ok";
+    if (proofRequired && proofFound) {
+      result.summary = "Proof found. Stop allowed.";
+    } else {
+      result.summary = "Proof not required for this task. Stop allowed.";
+    }
+    result.safeNextAction = null;
+    result.reasonCodes = ["BLOCKING_HOOK", "STOP_ALLOWED"];
+  }
+
+  const receiptPath = writeReceipt(cwd, "Stop", result);
+  result.receiptPath = receiptPath;
+  writeLedgerEntry(cwd, "Stop", result);
+
+  return result;
+}
+
+// ── SessionEnd ────────────────────────────────────────────────────────────────
+
+function handleSessionEnd(cwd, input = {}, options = {}) {
+  const handlerId = makeHandlerId();
+
+  const result = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    handlerId,
+    event: "SessionEnd",
+    blocking: false,
+    status: "ok",
+    createdAt: nowIso(),
+    actions: [],
+    summary: null,
+    redacted: true,
+  };
+
+  // Run outcome summary
+  try {
+    const outcomePath = path.join(cwd, ".claude/cco/orchestration/seamless-outcome/latest-outcome.json");
+    const outcome = safeReadJson(outcomePath);
+    if (outcome) {
+      result.actions.push({ action: "outcome_summary_read", status: "ok" });
+      result.outcomeSummary = {
+        status: outcome.status || "unknown",
+        redacted: true,
+      };
+    } else {
+      result.actions.push({ action: "outcome_summary_read", status: "not_found" });
+    }
+  } catch {
+    result.actions.push({ action: "outcome_summary_read", status: "skipped" });
+  }
+
+  // Update ledger (via product-learning event)
+  try {
+    const { appendProductLearningEvent } = require("./product-learning-events");
+    appendProductLearningEvent(cwd, {
+      eventName: "lifecycle_session_end_summary_written",
+      payload: {
+        event: "SessionEnd",
+        handlerId,
+        status: "ok",
+        redacted: true,
+      },
+    });
+    result.actions.push({ action: "ledger_updated", status: "ok" });
+  } catch {
+    result.actions.push({ action: "ledger_updated", status: "skipped" });
+  }
+
+  // Read company-loop status
+  try {
+    const loopPath = path.join(cwd, ".claude/cco/orchestration/company-loop/latest-report.json");
+    const loop = safeReadJson(loopPath);
+    if (loop) {
+      result.actions.push({ action: "company_loop_read", status: "ok" });
+      result.companyLoopStatus = {
+        status: loop.status || "unknown",
+        nextPrRecommendation: (loop.surface && loop.surface.recommendedNextPr) || null,
+        redacted: true,
+      };
+    } else {
+      result.actions.push({ action: "company_loop_read", status: "not_found" });
+    }
+  } catch {
+    result.actions.push({ action: "company_loop_read", status: "skipped" });
+  }
+
+  // Prepare handoff summary
+  try {
+    const handoffPath = path.join(cwd, ".claude/cco/orchestration/worker-handoff/latest-handoff.json");
+    const handoff = safeReadJson(handoffPath);
+    if (handoff) {
+      result.actions.push({ action: "handoff_summary_prepared", status: "ok" });
+      result.handoffStatus = { available: true, redacted: true };
+    } else {
+      result.actions.push({ action: "handoff_summary_prepared", status: "not_found" });
+      result.handoffStatus = { available: false, redacted: true };
+    }
+  } catch {
+    result.actions.push({ action: "handoff_summary_prepared", status: "skipped" });
+    result.handoffStatus = { available: false, redacted: true };
+  }
+
+  result.summary = "Session end: outcome, ledger, company-loop, and handoff updated.";
+  result.safeNextAction = null;
+  result.reasonCodes = ["NON_BLOCKING", "OUTCOME_WRITTEN", "LEDGER_UPDATED", "HANDOFF_PREPARED"];
+
+  const receiptPath = writeReceipt(cwd, "SessionEnd", result);
+  result.receiptPath = receiptPath;
+  writeLedgerEntry(cwd, "SessionEnd", result);
+
+  return result;
+}
+
+// ── Dispatcher ────────────────────────────────────────────────────────────────
+
+// ── Recursion guard ───────────────────────────────────────────────────────────
+// Prevents Avorelo lifecycle hooks from re-entering when a hook-triggered
+// command itself calls another Avorelo command (e.g. lifecycle-hook → run →
+// lifecycle-hook). The environment variable is set by the shell hook wrapper
+// and checked here before any handler runs.
+
+const RECURSION_GUARD_ENV = "AVORELO_HOOK_ACTIVE";
+
+function isRecursionGuardActive() {
+  return process.env[RECURSION_GUARD_ENV] === "1";
+}
+
+function buildRecursionSkippedResult(event) {
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    event,
+    status: "ok",
+    recursionSkipped: true,
+    blocking: false,
+    decision: "allow",
+    summary: "Recursion guard active. Lifecycle re-entry skipped.",
+    reasonCodes: ["RECURSION_GUARD_ACTIVE", "AVORELO_HOOK_ACTIVE_SET"],
+    redacted: true,
+  };
+}
+
+function handleLifecycleHook(cwd, event, input = {}, options = {}) {
+  // Recursion guard: if a hook-triggered command calls us again, skip silently
+  if (isRecursionGuardActive()) {
+    return buildRecursionSkippedResult(event);
+  }
+
+  switch (event) {
+    case "SessionStart":
+    case "session-start":
+      return handleSessionStart(cwd, input, options);
+    case "UserPromptSubmit":
+    case "user-prompt-submit":
+      return handleUserPromptSubmit(cwd, input, options);
+    case "PreToolUse":
+    case "pre-tool-use":
+      return handlePreToolUse(cwd, input, options);
+    case "PostToolUse":
+    case "post-tool-use":
+      return handlePostToolUse(cwd, input, options);
+    case "Stop":
+    case "stop":
+      return handleStop(cwd, input, options);
+    case "SessionEnd":
+    case "session-end":
+      return handleSessionEnd(cwd, input, options);
+    default:
+      return {
+        contract: CONTRACT,
+        schemaVersion: SCHEMA_VERSION,
+        event,
+        status: "error",
+        error: `Unknown lifecycle event: ${event}`,
+        reasonCodes: ["UNKNOWN_EVENT"],
+        redacted: true,
+      };
+  }
+}
+
+function formatLifecycleHookText(result, options = {}) {
+  const debug = options.debug || false;
+  const lines = [];
+
+  const statusLabel = result.status === "ok" ? "ok" : result.status === "blocked" ? "BLOCKED" : result.status;
+  lines.push(`Lifecycle hook [${result.event}]: ${statusLabel}`);
+
+  if (result.decision && result.decision !== "allow") {
+    lines.push(`Decision: ${result.decision}`);
+  }
+  if (result.summary) {
+    lines.push(`Summary: ${result.summary}`);
+  }
+  if (result.safeNextAction) {
+    lines.push(`Next: ${result.safeNextAction}`);
+  }
+
+  if (debug && result.actions && result.actions.length > 0) {
+    lines.push("", "Actions:");
+    for (const a of result.actions) {
+      lines.push(`  - ${a.action}: ${a.status}${a.reason ? ` (${a.reason})` : ""}`);
+    }
+    if (result.reasonCodes) {
+      lines.push("", `Reason codes: ${result.reasonCodes.join(", ")}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  HOOKS_DIR_REL,
+  RECURSION_GUARD_ENV,
+  handleLifecycleHook,
+  handleSessionStart,
+  handleUserPromptSubmit,
+  handlePreToolUse,
+  handlePostToolUse,
+  handleStop,
+  handleSessionEnd,
+  formatLifecycleHookText,
+  isRecursionGuardActive,
+  buildRecursionSkippedResult,
+};