avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/cco-posttooluse.js

@@ -0,0 +1,504 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { readStdinJson, ensureCcoDirs, getEffectiveConfig, safeWriteJson, safeWriteText } = require("./lib/fsx");
+const { normalizeHookInput, outAdditional } = require("./lib/hook-contracts");
+const { readSecurityAllowlist } = require("./lib/config");
+const { logMetric } = require("./lib/metrics");
+const { extractRuntimeEvidence } = require("./lib/attribution");
+const { scanTextForSecurity } = require("./lib/security-scan");
+const { summarizeLargeObject } = require("./lib/tokenish");
+const { summarizeLargeOutput } = require("./lib/context-savings-engine");
+const { ValueLedger } = require("./lib/value-ledger");
+const { createRemediationJob } = require("./lib/remediation");
+const { selectMicroProofs, formatMicroProofContext } = require("./lib/micro-proof");
+const { createCanonicalProof, withCanonicalProof } = require("./lib/proof-canonical");
+const { ReentryMemoryStore } = require("./lib/reentry-memory-store");
+const { captureFromFailure, captureFromFileChange } = require("./lib/reentry-memory-capture");
+const { checkToolOutputSize, normalizeBudgetConfig } = require("./lib/context-budget-guard");
+
+const BUILTIN_TOOLS = new Set(["Bash", "Read", "Write", "Edit", "Glob", "Grep", "Agent", "WebFetch", "WebSearch", "Skill"]);
+
+function contentHash(text) {
+  return crypto.createHash("sha1").update(String(text || "")).digest("hex");
+}
+
+function loadScanHashState(cwd) {
+  const p = path.join(cwd, ".claude", "cco", "state", "scan-hashes.json");
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveScanHashState(cwd, state) {
+  const p = path.join(cwd, ".claude", "cco", "state", "scan-hashes.json");
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(state, null, 2), "utf8");
+}
+
+function logMaterialStep(cwd, params) {
+  const canonical = createCanonicalProof("material_step", params.proof || {});
+  logMetric(cwd, {
+    sessionId: params.sessionId,
+    event: params.event,
+    tool: params.tool,
+    action: params.action,
+    reasonCodes: params.reasonCodes || [],
+    meta: withCanonicalProof(params.meta || {}, canonical),
+  });
+}
+
+// Credential finding codes that always trigger a warning even when riskScore < 70.
+// SEC_GH_TOKEN scores ~66 but is credential-critical; SEC_PRIVATE_KEY scores >= 90.
+const CREDENTIAL_CODES = new Set(["SEC_PRIVATE_KEY", "SEC_GH_TOKEN"]);
+
+// Redact known credential patterns from a string. Used for MCP output replacement.
+function redactStringCredentials(text) {
+  if (typeof text !== "string") return text;
+  let s = text.replace(/-----BEGIN PRIVATE KEY-----[\s\S]*?-----END PRIVATE KEY-----/g, "[REDACTED:SEC_PRIVATE_KEY]");
+  s = s.replace(/ghp_[A-Za-z0-9]{20,}/g, "[REDACTED:SEC_GH_TOKEN]");
+  return s;
+}
+
+// Recursively redact credential strings in an object/array, preserving non-string fields.
+function redactObjectStrings(value) {
+  if (typeof value === "string") return redactStringCredentials(value);
+  if (Array.isArray(value)) return value.map(redactObjectStrings);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = redactObjectStrings(v);
+    return out;
+  }
+  return value;
+}
+
+// Build scan text from toolResponse: always JSON.stringify so ALL fields (stdout AND stderr)
+// are covered, not just the first non-null field.
+function buildScanText(toolResponse) {
+  if (!toolResponse) return null;
+  if (typeof toolResponse === "string") {
+    return toolResponse.length > 50000 ? toolResponse.slice(0, 50000) : toolResponse;
+  }
+  try {
+    const s = JSON.stringify(toolResponse);
+    return s.length > 50000 ? s.slice(0, 50000) : s;
+  } catch { return null; }
+}
+
+async function main() {
+  const raw = await readStdinJson();
+  const input = normalizeHookInput(raw);
+  const cwd = input.cwd;
+  const sessionId = input.session_id;
+  const toolName = input.tool_name;
+  const toolInput = input.tool_input;
+  const toolResponse = input.tool_response;
+  const hookEventName = input.hook_event_name || "PostToolUse";
+  const runtimeEvidence = extractRuntimeEvidence({
+    tool: toolName,
+    event: hookEventName,
+    toolInput,
+    toolResponse,
+  }) || {};
+
+  ensureCcoDirs(cwd);
+  const { config } = getEffectiveConfig(cwd);
+  const ledger = new ValueLedger(cwd);
+  const allowlist = readSecurityAllowlist(cwd, config);
+
+  if ((toolName === "Write" || toolName === "Edit") && toolInput && toolInput.file_path) {
+    const filePath = toolInput.file_path;
+    const content = typeof toolInput.content === "string" ? toolInput.content : "";
+
+    const hashState = loadScanHashState(cwd);
+    const h = contentHash(content);
+    if (hashState[filePath] && hashState[filePath] === h) {
+      logMaterialStep(cwd, {
+        sessionId,
+        event: "PostToolUse",
+        tool: toolName,
+        action: "scanSkipped",
+        reasonCodes: ["CTX_SCAN_SKIPPED_UNCHANGED"],
+        meta: { filePath },
+        proof: {
+          step_type: "scan_skipped",
+          value_type: "efficiency",
+          artifact_ref: null,
+          evidence_refs: [],
+          user_visible_proof_supported: false,
+          notes: "Skipped security scan because file content hash was unchanged.",
+          reason_codes: ["CTX_SCAN_SKIPPED_UNCHANGED"],
+        },
+      });
+      return process.stdout.write(JSON.stringify({}));
+    }
+
+    hashState[filePath] = h;
+    saveScanHashState(cwd, hashState);
+
+    const report = scanTextForSecurity({ text: content, pathHint: filePath, allowlist });
+    const outPath = `.claude/cco/security/${Date.now()}-file-scan.json`;
+    safeWriteJson(cwd, outPath, report);
+
+    if (Array.isArray(report.suppressionAudit) && report.suppressionAudit.length) {
+      const auditPath = `.claude/cco/security/${Date.now()}-suppression-audit.json`;
+      safeWriteJson(cwd, auditPath, { sessionId, filePath, suppressionAudit: report.suppressionAudit });
+      logMaterialStep(cwd, {
+        sessionId,
+        event: "PostToolUse",
+        tool: toolName,
+        action: "suppressionAudit",
+        reasonCodes: ["SEC_SUPPRESSION_AUDIT"],
+        meta: { filePath, auditPath, count: report.suppressionAudit.length },
+        proof: {
+          step_type: "suppression_audit",
+          value_type: "trust",
+          artifact_ref: auditPath,
+          evidence_refs: [auditPath],
+          user_visible_proof_supported: false,
+          notes: "Recorded suppression audit for ignored findings.",
+          reason_codes: ["SEC_SUPPRESSION_AUDIT"],
+        },
+      });
+    }
+
+    let remediation = null;
+    if (report.activeFindingsCount > 0) {
+      remediation = createRemediationJob(cwd, { sessionId, filePath, report });
+      logMaterialStep(cwd, {
+        sessionId,
+        event: "PostToolUse",
+        tool: toolName,
+        action: "remediationSuggested",
+        reasonCodes: ["SEC_REMEDIATION_JOB_CREATED", ...(report.topReasons || [])],
+        meta: {
+          profile: config.profile,
+          tier: config.tier,
+          jobPath: remediation.jobPath,
+          riskClass: remediation.job.riskClass,
+        },
+        proof: {
+          step_type: "remediation_created",
+          value_type: "trust",
+          artifact_ref: remediation.jobPath,
+          evidence_refs: [remediation.jobPath],
+          recovery_triggered: true,
+          user_visible_proof_supported: true,
+          notes: "Created remediation guidance for active security findings.",
+          reason_codes: ["SEC_REMEDIATION_JOB_CREATED", ...(report.topReasons || [])],
+        },
+      });
+    }
+
+    logMaterialStep(cwd, {
+      sessionId,
+      event: "PostToolUse",
+      tool: toolName,
+      action: "scan",
+      reasonCodes: report.topReasons || [],
+      meta: {
+        profile: config.profile,
+        tier: config.tier,
+        filePath,
+        riskScore: report.riskScore,
+        activeFindingsCount: report.activeFindingsCount,
+      },
+      proof: {
+        step_type: report.activeFindingsCount > 0 ? "security_finding" : "other",
+        value_type: "trust",
+        artifact_ref: outPath,
+        evidence_refs: remediation ? [outPath, remediation.jobPath] : [outPath],
+        recovery_triggered: remediation ? true : null,
+        user_visible_proof_supported: report.activeFindingsCount > 0,
+        notes:
+          report.activeFindingsCount > 0
+            ? "Security scan produced active findings."
+            : "Security scan completed with no active findings.",
+        reason_codes: report.topReasons || [],
+      },
+    });
+
+    if (report.riskScore >= 70) {
+      const rem = remediation ? ` Remediation job: ${remediation.jobPath}.` : "";
+      let msg = `Security scan flagged HIGH risk (${(report.topReasons || []).join(", ")}). See ${outPath}.${rem}`;
+
+      try {
+        const proofCodes = remediation
+          ? ["SEC_REMEDIATION_JOB_CREATED"]
+          : (report.topReasons || []).filter((c) => String(c).startsWith("SEC_"));
+        const proofEnabled =
+          config.proofSystem?.enabled !== false &&
+          config.proofSystem?.microProofEnabled !== false;
+        const { proofs } = selectMicroProofs(proofCodes, cwd, sessionId, { proofEnabled });
+        const proofText = formatMicroProofContext(proofs);
+        if (proofText) msg += ` ${proofText}`;
+      } catch {}
+
+      return process.stdout.write(JSON.stringify(outAdditional("PostToolUse", msg)));
+    }
+
+    if (report.riskScore < 70) {
+      try {
+        const memStore = new ReentryMemoryStore(cwd, config.memory);
+        captureFromFileChange(memStore, { sessionId, filePath, summary: `${toolName} on ${filePath} (risk: ${report.riskScore})` });
+      } catch { /* non-fatal */ }
+    }
+
+    return process.stdout.write(JSON.stringify({}));
+  }
+
+  if (hookEventName === "PostToolUseFailure") {
+    const hint =
+      "Tool failed. Avoid blind retries: inspect stderr, narrow inputs, and run avorelo status for quick remediation hints.";
+    logMaterialStep(cwd, {
+      sessionId,
+      event: "PostToolUseFailure",
+      tool: toolName,
+      action: "guidance",
+      reasonCodes: ["FAIL_RETRY_GUARD"],
+      meta: { profile: config.profile, tier: config.tier },
+      proof: {
+        step_type: "retry_guard",
+        value_type: "control",
+        artifact_ref: null,
+        evidence_refs: [],
+        recovery_triggered: true,
+        user_visible_proof_supported: true,
+        notes: hint,
+        reason_codes: ["FAIL_RETRY_GUARD"],
+      },
+    });
+
+    try {
+      const memStore = new ReentryMemoryStore(cwd, config.memory);
+      captureFromFailure(memStore, { sessionId, toolName, summary: `${toolName} failed`, errorText: String(input.tool_response || "") });
+    } catch { /* non-fatal */ }
+
+    let microProofSuffix = "";
+    try {
+      const proofEnabled =
+        config.proofSystem?.enabled !== false &&
+        config.proofSystem?.microProofEnabled !== false;
+      const { proofs } = selectMicroProofs(["FAIL_RETRY_GUARD"], cwd, sessionId, {
+        proofEnabled,
+      });
+      const proofText = formatMicroProofContext(proofs);
+      if (proofText) microProofSuffix = ` ${proofText}`;
+    } catch {}
+
+    return process.stdout.write(
+      JSON.stringify(outAdditional("PostToolUseFailure", `${hint}${microProofSuffix}`))
+    );
+  }
+
+  // Scan Bash, Read, and non-builtin MCP tool responses for sensitive data patterns.
+  // Write/Edit have their own file-content scan above; they are excluded here.
+  // JSON.stringify scan text ensures ALL fields (stdout AND stderr) are covered.
+  const SCAN_RESPONSE_TOOLS = new Set(["Bash", "Read"]);
+  const shouldScanResponse = SCAN_RESPONSE_TOOLS.has(toolName) || !BUILTIN_TOOLS.has(toolName);
+
+  if (shouldScanResponse) {
+    try {
+      const scanText = buildScanText(toolResponse);
+      if (scanText) {
+        const scanResult = scanTextForSecurity({ text: scanText, pathHint: `${toolName}-output`, allowlist });
+        if (scanResult.activeFindingsCount > 0) {
+          const codes = scanResult.topReasons || [];
+          const hasCredential = codes.some((c) => CREDENTIAL_CODES.has(c));
+          // Warn if riskScore >= 70 OR output contains a credential-like pattern.
+          // SEC_GH_TOKEN scores ~66 (below global threshold) but is always credential-critical.
+          const warningEmitted = scanResult.riskScore >= 70 || hasCredential;
+
+          // For MCP (non-builtin) tools: redact credential strings and replace output via
+          // updatedMCPToolOutput — this is real PRE_CONTEXT saving (Claude Code honors it).
+          // For built-in tools (Bash/Read): output already reached Claude before this hook ran;
+          // no replacement schema exists for built-ins, so warning-only is the honest behavior.
+          let redactionHappened = false;
+          let updatedMCPOutput = null;
+          if (warningEmitted && !BUILTIN_TOOLS.has(toolName) && hasCredential) {
+            try {
+              const redacted = redactObjectStrings(toolResponse);
+              updatedMCPOutput = JSON.stringify(redacted);
+              redactionHappened = true;
+            } catch { /* fail-open: keep redactionHappened=false */ }
+          }
+
+          logMaterialStep(cwd, {
+            sessionId,
+            event: "PostToolUse",
+            tool: toolName,
+            action: "sensitiveOutputDetected",
+            reasonCodes: ["SEC_OUTPUT_SENSITIVE_DATA", ...codes],
+            meta: {
+              profile: config.profile,
+              tier: config.tier,
+              riskScore: scanResult.riskScore,
+              activeFindingsCount: scanResult.activeFindingsCount,
+              findingCodes: codes,
+              warningEmitted,
+              redactionHappened,
+            },
+            proof: {
+              step_type: "security_finding",
+              value_type: "control",
+              artifact_ref: null,
+              evidence_refs: [],
+              user_visible_proof_supported: warningEmitted,
+              notes: redactionHappened
+                ? `Sensitive data redacted from MCP tool output before model context.`
+                : `Sensitive data pattern detected in ${toolName} tool output; warning emitted.`,
+              reason_codes: ["SEC_OUTPUT_SENSITIVE_DATA", ...codes],
+            },
+          });
+
+          if (warningEmitted) {
+            const codeStr = codes.join(", ") || "SEC_OUTPUT_SENSITIVE_DATA";
+            // Only claim redaction for MCP where updatedMCPToolOutput actually replaces output.
+            // For built-in tools, raw output already reached Claude — warning only.
+            const msg = redactionHappened
+              ? `Avorelo redacted sensitive data from MCP tool output (${codeStr}). Raw credential values removed before model context.`
+              : `Avorelo detected sensitive data in ${toolName} output (${codeStr}). Review before using this output. Do not log or store raw values.`;
+
+            const hookOut = outAdditional("PostToolUse", msg);
+            if (redactionHappened && updatedMCPOutput !== null) {
+              return process.stdout.write(JSON.stringify({
+                updatedMCPToolOutput: updatedMCPOutput,
+                ...hookOut,
+              }));
+            }
+            return process.stdout.write(JSON.stringify(hookOut));
+          }
+        }
+      }
+    } catch {
+      // Fail-open: scanner errors must never break tool output delivery.
+      try {
+        logMaterialStep(cwd, {
+          sessionId, event: "PostToolUse", tool: toolName, action: "scanError",
+          reasonCodes: [],
+          meta: { profile: config.profile, tier: config.tier },
+          proof: {
+            step_type: "other", value_type: "control",
+            artifact_ref: null, evidence_refs: [],
+            user_visible_proof_supported: false,
+            notes: "Security scanner threw during response scan; failing open.",
+            reason_codes: [],
+          },
+        });
+      } catch { /* double fail-open */ }
+    }
+  }
+
+  // Detect large output — do NOT pass ledger here; we only emit a ledger event
+  // for MCP tools below (where updatedMCPToolOutput genuinely replaces what Claude sees).
+  // For built-in tools (Bash etc.) we emit additionalContext only, which adds context rather
+  // than saving it — no savings event is claimed.
+  const { summary } = summarizeLargeOutput(toolResponse, null, { sessionId, toolName });
+  if (summary && summary.isLarge) {
+    const artifactPath = `.claude/cco/state/tool-response-${Date.now()}.txt`;
+    safeWriteText(cwd, artifactPath, JSON.stringify(toolResponse, null, 2));
+
+    logMaterialStep(cwd, {
+      sessionId,
+      event: "PostToolUse",
+      tool: toolName,
+      action: "largeOutputStored",
+      reasonCodes: ["CTX_LARGE_OUTPUT"],
+      meta: { profile: config.profile, tier: config.tier, bytes: summary.bytes, artifactPath },
+      proof: {
+        step_type: "large_output_managed",
+        value_type: "efficiency",
+        artifact_ref: artifactPath,
+        evidence_refs: [artifactPath],
+        user_visible_proof_supported: true,
+        notes: "Stored large tool output out-of-band to reduce context pressure.",
+        reason_codes: ["CTX_LARGE_OUTPUT"],
+        bytes: summary.bytes,
+        output_artifact_type: "tool_output_snapshot",
+        output_artifact_reference: artifactPath,
+      },
+    });
+
+    let microProofSuffix = "";
+    try {
+      const proofEnabled =
+        config.proofSystem?.enabled !== false &&
+        config.proofSystem?.microProofEnabled !== false;
+      const { proofs } = selectMicroProofs(["CTX_LARGE_OUTPUT"], cwd, sessionId, {
+        proofEnabled,
+      });
+      const proofText = formatMicroProofContext(proofs);
+      if (proofText) microProofSuffix = ` ${proofText}`;
+    } catch {}
+
+    const additionalContext = `Tool output was large; stored full output at ${artifactPath}. Use the stored file instead of re-running the tool.${microProofSuffix}`;
+
+    if (!BUILTIN_TOOLS.has(toolName)) {
+      // MCP tool: updatedMCPToolOutput replaces the tool response before Claude sees it.
+      // This is a genuine PRE_CONTEXT saving — emit the ledger event here only.
+      const savedBytes = Math.max(0, summary.bytes - Buffer.byteLength(summary.preview || "", "utf8"));
+      ledger.append({
+        bucket: "large_output_referenced",
+        sessionId,
+        label: `MCP large output replaced: ${summary.bytes} bytes → preview`,
+        savedBytes,
+        savedTokens: Math.round(savedBytes / 4),
+        notes: `tool=${toolName}`,
+        artifactRef: artifactPath,
+      });
+      return process.stdout.write(
+        JSON.stringify({
+          updatedMCPToolOutput: summary.preview,
+          ...outAdditional("PostToolUse", additionalContext),
+        })
+      );
+    }
+
+    // Built-in tool (Bash, Read, etc.): additionalContext only — adds guidance, does not replace
+    // the tool response Claude already received. No ledger savings event for this path.
+    return process.stdout.write(JSON.stringify(outAdditional("PostToolUse", additionalContext)));
+  }
+
+  if (config.contextBudgetGuard?.enabled) {
+    const budget = normalizeBudgetConfig(config.contextBudgetGuard);
+    const rawText = typeof toolResponse === "string" ? toolResponse : JSON.stringify(toolResponse ?? "");
+    const sizeCheck = checkToolOutputSize(rawText, budget);
+    if (sizeCheck.isOversized) {
+      logMaterialStep(cwd, {
+        sessionId,
+        event: "PostToolUse",
+        tool: toolName,
+        action: "budgetOutputWarning",
+        reasonCodes: ["CTX_BUDGET_OUTPUT_OVERSIZED"],
+        meta: { bytes: sizeCheck.bytes, maxBytes: sizeCheck.maxBytes },
+        proof: {
+          step_type: "budget_output_warning",
+          value_type: "efficiency",
+          artifact_ref: null,
+          evidence_refs: [],
+          user_visible_proof_supported: true,
+          notes: "Tool output exceeded configured context budget output threshold.",
+          reason_codes: ["CTX_BUDGET_OUTPUT_OVERSIZED"],
+        },
+      });
+      return process.stdout.write(JSON.stringify(outAdditional("PostToolUse", sizeCheck.truncateHint)));
+    }
+  }
+
+  logMetric(cwd, {
+    ...runtimeEvidence,
+    sessionId,
+    event: "PostToolUse",
+    tool: toolName,
+    action: "noop",
+    reasonCodes: [],
+    meta: { profile: config.profile, tier: config.tier },
+  });
+  process.stdout.write(JSON.stringify({}));
+}
+
+main().catch(() => process.stdout.write(JSON.stringify({})));