avorelo 0.1.0

package/scripts/lib/hook-contracts.js

@@ -0,0 +1,290 @@
+"use strict";
+
+const HOOK_EVENT_NAMES = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PostToolUse",
+  "PostToolUseFailure",
+  "InstructionsLoaded",
+  "ConfigChange",
+  "PermissionRequest",
+  "Notification",
+  "SubagentStart",
+  "SubagentStop",
+  "Stop",
+  "TeammateIdle",
+  "TaskCompleted",
+  "WorktreeCreate",
+  "WorktreeRemove",
+  "PreCompact",
+  "SessionEnd",
+];
+
+const HOOK_CONTRACTS_V2 = {
+  SessionStart: {
+    eventName: "SessionStart",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id"],
+    outputSchema: "{}",
+    timeoutMs: 3000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["ONBOARDING_HINT_READY", "SEC_TRUST_AUDIT"],
+  },
+  UserPromptSubmit: {
+    eventName: "UserPromptSubmit",
+    requiredInputs: ["cwd", "prompt"],
+    optionalInputs: ["session_id"],
+    outputSchema: "{} | {hookSpecificOutput.additionalContext}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["PROMPT_NO_DOD", "PROMPT_NO_OUTPUT_FORMAT", "PROMPT_NO_CONSTRAINTS"],
+  },
+  PreToolUse: {
+    eventName: "PreToolUse",
+    requiredInputs: ["cwd", "tool_name"],
+    optionalInputs: ["session_id", "tool_input"],
+    outputSchema: "{} | {hookSpecificOutput.permissionDecision}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["LOOP_REPEATED_TOOL", "SEC_CURL_PIPE_SH", "TEAM_BLOCK_PATTERN"],
+  },
+  PostToolUse: {
+    eventName: "PostToolUse",
+    requiredInputs: ["cwd", "tool_name"],
+    optionalInputs: ["session_id", "tool_input", "tool_response"],
+    outputSchema: "{} | {hookSpecificOutput.additionalContext} | {updatedMCPToolOutput}",
+    timeoutMs: 5000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["CTX_LARGE_OUTPUT", "SEC_REMEDIATION_JOB_CREATED"],
+  },
+  PostToolUseFailure: {
+    eventName: "PostToolUseFailure",
+    requiredInputs: ["cwd", "tool_name"],
+    optionalInputs: ["session_id", "tool_input", "tool_response"],
+    outputSchema: "{} | {hookSpecificOutput.additionalContext}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["FAIL_RETRY_GUARD"],
+  },
+  InstructionsLoaded: {
+    eventName: "InstructionsLoaded",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id"],
+    outputSchema: "{}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["INSTRUCTIONS_REFRESH"],
+  },
+  ConfigChange: {
+    eventName: "ConfigChange",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id"],
+    outputSchema: "{}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["CONFIG_REFRESH"],
+  },
+  PermissionRequest: {
+    eventName: "PermissionRequest",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id", "tool_name", "tool_input", "permission_request"],
+    outputSchema: "{} | {hookSpecificOutput.permissionDecision}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["PERM_REQ_ALLOW", "PERM_REQ_ASK", "PERM_REQ_DENY", "PERM_FATIGUE_CONSOLIDATED"],
+  },
+  Notification: {
+    eventName: "Notification",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id", "message", "notification"],
+    outputSchema: "{} | {hookSpecificOutput.additionalContext}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["NOTIF_RECORDED", "NOTIF_DEDUPED"],
+  },
+  SubagentStart: {
+    eventName: "SubagentStart",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id", "subagent_id"],
+    outputSchema: "{} | {hookSpecificOutput.additionalContext}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["SUBAGENT_START", "CTX_COST_PRESSURE_SUBAGENT"],
+  },
+  SubagentStop: {
+    eventName: "SubagentStop",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id", "subagent_id"],
+    outputSchema: "{}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["SUBAGENT_STOP"],
+  },
+  Stop: {
+    eventName: "Stop",
+    requiredInputs: ["cwd"],
+    optionalInputs: [
+      "session_id",
+      "reason",
+      "next_bounded_action",
+      "rollback_available",
+      "reentry_status",
+      "claim_boundary",
+      "where_am_i_now",
+      "task_contract",
+    ],
+    outputSchema: "{}",
+    timeoutMs: 3000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["STOP_SNAPSHOT"],
+  },
+  TeammateIdle: {
+    eventName: "TeammateIdle",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id", "message"],
+    outputSchema: "{} | {hookSpecificOutput.additionalContext}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["IDLE_EVENT", "IDLE_DEFERRED_SCAN"],
+  },
+  TaskCompleted: {
+    eventName: "TaskCompleted",
+    requiredInputs: ["cwd"],
+    optionalInputs: [
+      "session_id",
+      "task_id",
+      "reason",
+      "next_bounded_action",
+      "claim_boundary",
+      "where_am_i_now",
+      "reentry_status",
+      "unresolved_items",
+      "task_contract",
+    ],
+    outputSchema: "{} | {hookSpecificOutput.additionalContext}",
+    timeoutMs: 2000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["TASK_COMPLETED"],
+  },
+  WorktreeCreate: {
+    eventName: "WorktreeCreate",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id", "worktree_path"],
+    outputSchema: "{} | {hookSpecificOutput.additionalContext}",
+    timeoutMs: 3000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["WORKTREE_EVENT", "SEC_TRUST_AUDIT"],
+  },
+  WorktreeRemove: {
+    eventName: "WorktreeRemove",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id", "worktree_path"],
+    outputSchema: "{}",
+    timeoutMs: 3000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["WORKTREE_EVENT"],
+  },
+  PreCompact: {
+    eventName: "PreCompact",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id", "transcript_path"],
+    outputSchema: "{}",
+    timeoutMs: 3000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["CTX_SNAPSHOT"],
+  },
+  SessionEnd: {
+    eventName: "SessionEnd",
+    requiredInputs: ["cwd"],
+    optionalInputs: ["session_id", "reason"],
+    outputSchema: "{}",
+    timeoutMs: 5000,
+    failOpenPolicy: "return {}",
+    reasonCodeMap: ["REPORT_WRITTEN", "TEAM_ROLLUP_WRITTEN"],
+  },
+};
+
+function safeReadString(value, fallback = "") {
+  return typeof value === "string" ? value : fallback;
+}
+
+function safeReadOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function safeReadBoolean(value) {
+  return typeof value === "boolean" ? value : null;
+}
+
+function safeReadObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+function safeReadArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function normalizeHookInput(input) {
+  const i = input || {};
+  return {
+    cwd: safeReadString(i.cwd, process.cwd()),
+    session_id: safeReadString(i.session_id, "unknown"),
+    hook_event_name: safeReadString(i.hook_event_name, ""),
+    tool_name: safeReadString(i.tool_name, ""),
+    tool_input: i.tool_input && typeof i.tool_input === "object" ? i.tool_input : {},
+    tool_response: i.tool_response && typeof i.tool_response === "object" ? i.tool_response : {},
+    prompt: safeReadString(i.prompt, ""),
+    transcript_path: safeReadString(i.transcript_path, ""),
+    reason: safeReadString(i.reason, "other"),
+    message: safeReadString(i.message, safeReadString(i.notification?.message, "")),
+    notification: i.notification && typeof i.notification === "object" ? i.notification : {},
+    permission_request: i.permission_request && typeof i.permission_request === "object" ? i.permission_request : {},
+    subagent_id: safeReadString(i.subagent_id, safeReadString(i.subagent?.id, "")),
+    task_id: safeReadString(i.task_id, safeReadString(i.task?.id, "")),
+    worktree_path: safeReadString(i.worktree_path, safeReadString(i.worktree?.path, "")),
+    next_bounded_action: typeof i.next_bounded_action === "string" ? i.next_bounded_action : safeReadObject(i.next_bounded_action),
+    rollback_available: safeReadBoolean(i.rollback_available),
+    claim_boundary: safeReadOptionalString(i.claim_boundary),
+    where_am_i_now: safeReadOptionalString(i.where_am_i_now),
+    reentry_status: safeReadOptionalString(i.reentry_status),
+    unresolved_items: safeReadArray(i.unresolved_items),
+    task_contract: safeReadObject(i.task_contract),
+  };
+}
+
+function outPermission(eventNameOrDecision, decisionOrReason, maybeReason) {
+  const eventName = maybeReason === undefined ? "PreToolUse" : eventNameOrDecision;
+  const decision = maybeReason === undefined ? eventNameOrDecision : decisionOrReason;
+  const reason = maybeReason === undefined ? decisionOrReason : maybeReason;
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      permissionDecision: decision,
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+function outAdditional(event, text) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: event,
+      additionalContext: text,
+    },
+  };
+}
+
+function isKnownHookEvent(eventName) {
+  return HOOK_EVENT_NAMES.includes(String(eventName || ""));
+}
+
+module.exports = {
+  HOOK_EVENT_NAMES,
+  HOOK_CONTRACTS_V2,
+  normalizeHookInput,
+  outPermission,
+  outAdditional,
+  isKnownHookEvent,
+};

package/scripts/lib/hook-safety-boundary-readiness.js

@@ -0,0 +1,80 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { nowIso } = require("./fsx");
+
+const CONTRACT = "avorelo.hookSafetyBoundaryReadiness.v1";
+const SCHEMA_VERSION = 1;
+const DOCTOR_REL = ".claude/cco/orchestration/hook-apply/latest-doctor.json";
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function buildHookSafetyBoundaryReadiness(cwd) {
+  const doctor = safeReadJson(path.join(cwd, DOCTOR_REL));
+  const installPrompt = safeReadJson(path.join(cwd, ".claude/cco/orchestration/ai-install/latest-prompt.json"));
+
+  let approvalBoundaryExported = false;
+  let rollbackAvailable = false;
+  try {
+    const mod = require("./hook-apply");
+    approvalBoundaryExported = typeof mod.requiresExplicitApproval === "function";
+    rollbackAvailable = typeof mod.rollbackHookApply === "function";
+  } catch {
+    approvalBoundaryExported = false;
+    rollbackAvailable = false;
+  }
+
+  const hasApprovalBoundaries = Array.isArray(installPrompt?.approvalBoundaries) && installPrompt.approvalBoundaries.length > 0;
+  const doctorFailed = (doctor?.summary?.fail || 0) > 0 || doctor?.status === "fail" || doctor?.status === "error";
+
+  const missingEvidence = [];
+  const safeNextActions = [];
+
+  if (!doctor) {
+    missingEvidence.push("Hook doctor artifact is missing.");
+    safeNextActions.push("Run: node bin/avorelo hooks doctor --json");
+  }
+  if (doctorFailed) {
+    missingEvidence.push("Hook doctor reports failing safety checks.");
+    safeNextActions.push("Run: node bin/avorelo hooks doctor --json and resolve failures");
+  }
+  if (!approvalBoundaryExported || !hasApprovalBoundaries) {
+    missingEvidence.push("Explicit approval boundaries are not clearly enforced across hook surfaces.");
+    safeNextActions.push("Run: node bin/avorelo install-ai --json");
+  }
+
+  const status = missingEvidence.length === 0 ? "pass" : "warn";
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    artifactPath: DOCTOR_REL,
+    hookDoctorAvailable: doctor !== null,
+    hookDoctorStatus: doctor?.status || "missing",
+    approvalBoundaryExported,
+    installPromptBoundariesAvailable: hasApprovalBoundaries,
+    rollbackAvailable,
+    hooksApplied: doctor?.hooksApplied === true,
+    missingEvidence,
+    safeNextActions: safeNextActions.length ? safeNextActions : ["Run: node bin/avorelo full-readiness --json"],
+    redacted: true,
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  DOCTOR_REL,
+  buildHookSafetyBoundaryReadiness,
+};