chainlesschain 0.166.9 → 0.166.13

package/src/lib/hook-runtime-contract.cjs

@@ -0,0 +1,291 @@
+"use strict";
+
+/**
+ * Canonical Hook runtime contract.
+ *
+ * Every Hook surface (Hooks v2, settings adapters, the SQLite registry, the
+ * replay bus and product producers) projects from this file.  Keep this module
+ * CommonJS so both the legacy CJS settings loader and ESM runtime can consume
+ * the exact same frozen objects without maintaining parallel registries.
+ */
+
+const HOOK_EVENT_SCHEMA_VERSION = 1;
+const MAX_HOOK_CONTEXT_BYTES = 1024 * 1024;
+const MIN_HOOK_TIMEOUT_MS = 1;
+const MAX_HOOK_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_HOOK_TIMEOUT_MS = 30 * 1000;
+
+const HOOK_PRIORITY = Object.freeze({
+  SYSTEM: 0,
+  HIGH: 100,
+  NORMAL: 500,
+  LOW: 900,
+  MONITOR: 1000,
+});
+
+const HOOK_EXECUTION_MODE = Object.freeze({
+  BLOCKING: "blocking",
+  ASYNC: "async",
+});
+
+const EVENT_GROUPS = Object.freeze({
+  system: ["Setup", "Notification", "TimelineEntry"],
+  tool: [
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PostToolBatch",
+    "ToolError",
+  ],
+  session: [
+    "UserPromptSubmit",
+    "UserPromptExpansion",
+    "AssistantResponse",
+    "SessionStart",
+    "SessionResume",
+    "SessionPause",
+    "SessionEnd",
+    "Stop",
+    "StopFailure",
+    "PreCompact",
+    "PostCompact",
+    "ModelSelection",
+  ],
+  permission: [
+    "PermissionRequest",
+    "PermissionAllow",
+    "PermissionDeny",
+    "PermissionDenied",
+    "ComplianceCheck",
+  ],
+  agent: [
+    "AgentStart",
+    "AgentStop",
+    "SubagentStart",
+    "SubagentStop",
+    "TaskAssigned",
+    "TaskCreated",
+    "TaskCompleted",
+    "TeammateIdle",
+  ],
+  plan: [
+    "PlanModeEnter",
+    "PlanRevised",
+    "PlanApproved",
+    "PlanItemExecute",
+    "PlanRejected",
+  ],
+  workspace: [
+    "InstructionsLoaded",
+    "CwdChanged",
+    "WorktreeCreate",
+    "WorktreeRemove",
+    "FileChanged",
+    "FileModified",
+    "PreFileAccess",
+    "PostFileAccess",
+  ],
+  git: [
+    "PreCommit",
+    "PostCommit",
+    "PreGitCommit",
+    "PostGitCommit",
+    "PreGitPush",
+    "CIFailure",
+  ],
+  mcp: [
+    "McpRequest",
+    "McpResponse",
+    "MCPElicitation",
+    "Elicitation",
+    "ElicitationResult",
+  ],
+  ipc: ["PreIPCCall", "PostIPCCall", "IPCError"],
+  memory: ["MemorySave", "MemoryLoad"],
+  governance: [
+    "ConfigChange",
+    "AuditLog",
+    "DataSubjectRequest",
+    "IterationWarning",
+    "IterationBudgetExhausted",
+  ],
+});
+
+const DECISION_EVENT_NAMES = new Set([
+  "Setup",
+  "PreToolUse",
+  "UserPromptSubmit",
+  "UserPromptExpansion",
+  "Stop",
+  "PermissionRequest",
+  "ModelSelection",
+  "PreCompact",
+  "ComplianceCheck",
+  "SubagentStart",
+  "SubagentStop",
+]);
+
+const CONTEXT_EVENT_NAMES = new Set([
+  "Setup",
+  "UserPromptSubmit",
+  "UserPromptExpansion",
+  "SessionStart",
+  "PostCompact",
+  "InstructionsLoaded",
+]);
+
+const eventEntries = [];
+for (const [group, names] of Object.entries(EVENT_GROUPS)) {
+  for (const event of names) eventEntries.push([event, group]);
+}
+
+const HOOK_EVENT_TYPES = Object.freeze(
+  Object.fromEntries(eventEntries.map(([event]) => [event, event])),
+);
+
+const DEFAULT_ALLOWED_EXECUTORS = Object.freeze([
+  "command",
+  "http",
+  "mcp_tool",
+  "prompt",
+  "agent",
+  "js",
+]);
+
+const HOOK_EVENT_CONTRACTS = Object.freeze(
+  Object.fromEntries(
+    eventEntries.map(([event, group]) => {
+      const decisionCapable = DECISION_EVENT_NAMES.has(event);
+      return [
+        event,
+        Object.freeze({
+          schemaVersion: HOOK_EVENT_SCHEMA_VERSION,
+          event,
+          group,
+          allowedExecutors: DEFAULT_ALLOWED_EXECUTORS,
+          decisionCapable,
+          contextCapable: CONTEXT_EVENT_NAMES.has(event),
+          blockingSemantics: decisionCapable
+            ? "strictest:block>ask>allow>continue"
+            : "observe-only",
+          asyncDecisionSemantics: "observe-only",
+        }),
+      ];
+    }),
+  ),
+);
+
+const DECISION_EVENTS = Object.freeze(new Set(DECISION_EVENT_NAMES));
+
+function stableStringify(value, seen = new Set()) {
+  if (value === null || typeof value !== "object") {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined) {
+      throw new TypeError("Hook event context contains a non-JSON value");
+    }
+    return encoded;
+  }
+  if (seen.has(value)) {
+    throw new TypeError("Hook event context must not contain cycles");
+  }
+  seen.add(value);
+  let encoded;
+  if (Array.isArray(value)) {
+    encoded = `[${value.map((item) => stableStringify(item, seen)).join(",")}]`;
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      seen.delete(value);
+      throw new TypeError("Hook event context must contain only plain objects");
+    }
+    const keys = Object.keys(value).sort();
+    encoded = `{${keys
+      .map(
+        (key) => `${JSON.stringify(key)}:${stableStringify(value[key], seen)}`,
+      )
+      .join(",")}}`;
+  }
+  seen.delete(value);
+  return encoded;
+}
+
+function validateHookEvent(event, context = {}) {
+  const contract = HOOK_EVENT_CONTRACTS[event];
+  if (!contract) {
+    const error = new Error(`Invalid hook event: ${event}`);
+    error.code = "CC_HOOK_EVENT_UNKNOWN";
+    throw error;
+  }
+  if (
+    context === null ||
+    typeof context !== "object" ||
+    Array.isArray(context)
+  ) {
+    const error = new TypeError("Hook event context must be a plain object");
+    error.code = "CC_HOOK_EVENT_CONTEXT_INVALID";
+    throw error;
+  }
+  let serialized;
+  try {
+    serialized = stableStringify(context);
+  } catch (cause) {
+    const error = new TypeError(
+      `Invalid hook event context: ${cause.message}`,
+      {
+        cause,
+      },
+    );
+    error.code = "CC_HOOK_EVENT_CONTEXT_INVALID";
+    throw error;
+  }
+  if (Buffer.byteLength(serialized, "utf8") > MAX_HOOK_CONTEXT_BYTES) {
+    const error = new RangeError(
+      `Hook event context exceeds ${MAX_HOOK_CONTEXT_BYTES} bytes`,
+    );
+    error.code = "CC_HOOK_EVENT_CONTEXT_TOO_LARGE";
+    throw error;
+  }
+  return contract;
+}
+
+function normalizeHookPriority(value, fallback = HOOK_PRIORITY.NORMAL) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(
+    HOOK_PRIORITY.SYSTEM,
+    Math.min(HOOK_PRIORITY.MONITOR, parsed),
+  );
+}
+
+function normalizeHookTimeoutMs(value, fallback = DEFAULT_HOOK_TIMEOUT_MS) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(
+    MIN_HOOK_TIMEOUT_MS,
+    Math.min(MAX_HOOK_TIMEOUT_MS, Math.floor(parsed)),
+  );
+}
+
+function normalizeHookExecutionMode(value) {
+  return value === HOOK_EXECUTION_MODE.ASYNC || value === true
+    ? HOOK_EXECUTION_MODE.ASYNC
+    : HOOK_EXECUTION_MODE.BLOCKING;
+}
+
+module.exports = {
+  HOOK_EVENT_SCHEMA_VERSION,
+  HOOK_EVENT_TYPES,
+  HOOK_EVENT_CONTRACTS,
+  DECISION_EVENTS,
+  HOOK_PRIORITY,
+  HOOK_EXECUTION_MODE,
+  DEFAULT_HOOK_TIMEOUT_MS,
+  MIN_HOOK_TIMEOUT_MS,
+  MAX_HOOK_TIMEOUT_MS,
+  MAX_HOOK_CONTEXT_BYTES,
+  stableStringify,
+  validateHookEvent,
+  normalizeHookPriority,
+  normalizeHookTimeoutMs,
+  normalizeHookExecutionMode,
+};

package/src/lib/hook-runtime-contract.js

@@ -0,0 +1,21 @@
+import contract from "./hook-runtime-contract.cjs";
+
+export const {
+  HOOK_EVENT_SCHEMA_VERSION,
+  HOOK_EVENT_TYPES,
+  HOOK_EVENT_CONTRACTS,
+  DECISION_EVENTS,
+  HOOK_PRIORITY,
+  HOOK_EXECUTION_MODE,
+  DEFAULT_HOOK_TIMEOUT_MS,
+  MIN_HOOK_TIMEOUT_MS,
+  MAX_HOOK_TIMEOUT_MS,
+  MAX_HOOK_CONTEXT_BYTES,
+  stableStringify,
+  validateHookEvent,
+  normalizeHookPriority,
+  normalizeHookTimeoutMs,
+  normalizeHookExecutionMode,
+} = contract;
+
+export default contract;

package/src/lib/hook-trust.js

@@ -0,0 +1,210 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  checkRecordedWorkspaceTrust,
+  recordWorkspaceTrustConsent,
+  revokeRecordedWorkspaceTrust,
+} from "./workspace-trust.js";
+import { stableStringify } from "./hook-runtime-contract.js";
+
+export const HOOK_TRUST_SCHEMA = "chainlesschain.hook-trust/v1";
+
+function sha256(label, value) {
+  return crypto
+    .createHash("sha256")
+    .update(`${label}\0`, "utf8")
+    .update(String(value), "utf8")
+    .digest("hex");
+}
+
+function serializableDefinition(hook = {}) {
+  return {
+    event: hook.event || null,
+    type: hook.type || null,
+    command: hook.command || null,
+    args: Array.isArray(hook.args) ? hook.args.map(String) : [],
+    url: hook.url || null,
+    method: hook.method || null,
+    headers: hook.headers || null,
+    server: hook.server || null,
+    tool: hook.tool || null,
+    template: hook.template || null,
+    agentName: hook.agentName || null,
+    skillName: hook.skillName || null,
+    matcher: hook.matcher || null,
+    priority: hook.priority ?? null,
+    timeoutMs: hook.timeoutMs ?? null,
+    executionMode: hook.executionMode || null,
+    sandboxPolicy: hook.sandboxPolicy || null,
+    requiredBoundaries: hook.requiredBoundaries || null,
+  };
+}
+
+export function computeHookDefinitionDigest(hook = {}) {
+  return sha256(
+    "chainlesschain.hook-definition.v1",
+    stableStringify(serializableDefinition(hook)),
+  );
+}
+
+export function normalizeHookAuthority(hook = {}) {
+  const raw = hook.authority || hook.authoritySource || {};
+  const kind = String(raw.kind || hook.origin || "programmatic").toLowerCase();
+  const sourceFile =
+    typeof raw.sourceFile === "string" && raw.sourceFile
+      ? path.resolve(raw.sourceFile)
+      : null;
+  const definitionDigest = computeHookDefinitionDigest(hook);
+  const sourceDigest =
+    typeof (raw.digest || raw.sourceDigest) === "string" &&
+    /^[a-f0-9]{64}$/iu.test(raw.digest || raw.sourceDigest)
+      ? String(raw.digest || raw.sourceDigest).toLowerCase()
+      : definitionDigest;
+  const requiresConsent =
+    raw.requiresConsent === true ||
+    (raw.requiresConsent !== false &&
+      new Set(["settings", "config", "project"]).has(kind));
+  const subject = String(
+    raw.subject || sourceFile || `${kind}:${hook.id || definitionDigest}`,
+  );
+  return Object.freeze({
+    schema: HOOK_TRUST_SCHEMA,
+    kind,
+    sourceFile,
+    sourceDigest,
+    definitionDigest,
+    subject,
+    requiresConsent,
+  });
+}
+
+function trustFailure(authority, status, error = null) {
+  return Object.freeze({
+    schema: HOOK_TRUST_SCHEMA,
+    trusted: false,
+    status,
+    decision: "deny",
+    authority,
+    audit: null,
+    errorCode: error?.code || null,
+  });
+}
+
+function verifyAuthoritySource(authority) {
+  if (!authority.requiresConsent || !authority.sourceFile) {
+    return { matches: true, error: null };
+  }
+  try {
+    const currentDigest = crypto
+      .createHash("sha256")
+      .update(fs.readFileSync(authority.sourceFile))
+      .digest("hex");
+    return {
+      matches: currentDigest === authority.sourceDigest,
+      error: null,
+    };
+  } catch (error) {
+    return { matches: false, error };
+  }
+}
+
+export function assessHookTrust(hook, { workspaceRoot } = {}) {
+  const authority = normalizeHookAuthority(hook);
+  if (!authority.requiresConsent) {
+    return Object.freeze({
+      schema: HOOK_TRUST_SCHEMA,
+      trusted: true,
+      status: "host-trusted",
+      decision: "allow",
+      authority,
+      audit: null,
+      errorCode: null,
+    });
+  }
+  const source = verifyAuthoritySource(authority);
+  if (!source.matches) {
+    return trustFailure(
+      authority,
+      source.error ? "source-unavailable" : "changed",
+      source.error,
+    );
+  }
+  if (typeof workspaceRoot !== "string" || !path.isAbsolute(workspaceRoot)) {
+    return trustFailure(authority, "workspace-unavailable");
+  }
+  try {
+    const result = checkRecordedWorkspaceTrust({
+      workspaceRoot,
+      source: "hooks",
+      subject: authority.subject,
+      evidenceFingerprint: authority.sourceDigest,
+    });
+    return Object.freeze({
+      schema: HOOK_TRUST_SCHEMA,
+      trusted: result.decision === "allow" && result.status === "trusted",
+      status: result.status,
+      decision: result.decision,
+      authority,
+      audit: result.audit,
+      errorCode: null,
+    });
+  } catch (error) {
+    return trustFailure(authority, "trust-store-unavailable", error);
+  }
+}
+
+export function approveHookAuthority(
+  authorityInput,
+  { workspaceRoot, now } = {},
+) {
+  const authority = normalizeHookAuthority({
+    id: authorityInput?.id || "approval",
+    event: authorityInput?.event || "Setup",
+    type: authorityInput?.type || "command",
+    command: authorityInput?.command || null,
+    authority: authorityInput,
+  });
+  const source = verifyAuthoritySource(authority);
+  if (!source.matches) {
+    const error = new Error(
+      source.error
+        ? `Hook authority source is unavailable: ${authority.sourceFile}`
+        : `Hook authority source changed: ${authority.sourceFile}`,
+      source.error ? { cause: source.error } : undefined,
+    );
+    error.code = source.error
+      ? "CC_HOOK_SOURCE_UNAVAILABLE"
+      : "CC_HOOK_SOURCE_CHANGED";
+    throw error;
+  }
+  if (!authority.requiresConsent) {
+    return assessHookTrust(
+      { authority, id: "approval", event: "Setup", type: "command" },
+      { workspaceRoot },
+    );
+  }
+  return recordWorkspaceTrustConsent({
+    workspaceRoot,
+    source: "hooks",
+    subject: authority.subject,
+    evidenceFingerprint: authority.sourceDigest,
+    consent: "explicit",
+    now,
+  });
+}
+
+export function revokeHookAuthority(authorityInput, { workspaceRoot } = {}) {
+  const authority = normalizeHookAuthority({
+    id: authorityInput?.id || "revocation",
+    event: authorityInput?.event || "Setup",
+    type: authorityInput?.type || "command",
+    command: authorityInput?.command || null,
+    authority: authorityInput,
+  });
+  return revokeRecordedWorkspaceTrust({
+    workspaceRoot,
+    source: "hooks",
+    subject: authority.subject,
+  });
+}

package/src/lib/hooks-v2-producers.js

@@ -1,6 +1,7 @@
 /**
- * Best-effort bridge from real runtime producers to Hooks v2.
- * Hook failures never change the surrounding agent or interaction result.
+ * Canonical bridge from real runtime producers to Hooks v2. Decision-capable
+ * callers await and enforce the result; observation-only callers may emit in
+ * the background.
  *
  * A headless host may subscribe to a particular session to project a small,
  * machine-readable lifecycle stream.  The projection deliberately excludes
@@ -8,6 +9,10 @@
  * credentials, paths, and user content.  The observer is diagnostic only and
  * is never allowed to affect a hook decision.
  */
+import { collectCanonicalAdapterHooks } from "./hook-runtime-adapters.js";
+import path from "node:path";
+import { runWithHostHooksV2Workspace } from "./hooks-v2-workspace-context.js";
+
 const sessionObservers = new Map();
 
 function safeId(value, max = 160) {
@@ -100,13 +105,54 @@ async function dispatchHooksV2Event(eventName, context, options) {
         results: [],
       };
     }
-    return await runtime.executeHooks(eventName, context, options);
+    const adapterHooks = collectCanonicalAdapterHooks(eventName, context, {
+      settingsHooks: options.settingsHooks,
+      hookDb: options.hookDb,
+      matchTarget:
+        options.matchTarget || context.tool_name || context.tool || "",
+      cwd: options.cwd || context.cwd || process.cwd(),
+      settingsFailureMode:
+        options.failClosed === true ? "fail-closed" : "ignore",
+    });
+    const runtimeOptions = {
+      ...options,
+      additionalHooks: [
+        ...(Array.isArray(options.additionalHooks)
+          ? options.additionalHooks
+          : []),
+        ...adapterHooks,
+      ],
+      auditRequired:
+        options.auditRequired == null
+          ? process.env.NODE_ENV !== "test"
+          : options.auditRequired,
+    };
+    delete runtimeOptions.settingsHooks;
+    delete runtimeOptions.hookDb;
+    delete runtimeOptions.matchTarget;
+    delete runtimeOptions.cwd;
+    const workspaceRoot = path.resolve(
+      options.workspaceRoot || options.cwd || process.cwd(),
+    );
+    delete runtimeOptions.workspaceRoot;
+    const registeredHooks = runtime.hooks?.get?.(eventName);
+    const hasCandidateHooks =
+      (Array.isArray(registeredHooks) && registeredHooks.length > 0) ||
+      runtimeOptions.additionalHooks.length > 0;
+    if (!hasCandidateHooks) {
+      return await runtime.executeHooks(eventName, context, runtimeOptions);
+    }
+    return await runWithHostHooksV2Workspace(workspaceRoot, () =>
+      runtime.executeHooks(eventName, context, runtimeOptions),
+    );
   } catch (error) {
+    const failClosed = options.failClosed === true;
     return {
-      success: options.failClosed !== true,
-      blocked: options.failClosed === true,
-      decision: options.failClosed === true ? "block" : "continue",
+      success: !failClosed,
+      blocked: failClosed,
+      decision: failClosed ? "block" : "continue",
       error: error?.message || String(error),
+      errorCode: error?.code || null,
       results: [],
     };
   }