chainlesschain 0.162.183 → 0.162.185

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

@@ -26,35 +26,79 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import broker from "./process-execution-broker/index.js";
 import hookEnvironment from "./hook-environment.cjs";
+import hookShellCommand from "./hook-shell-command.cjs";
 import permissionRules from "./permission-rules.cjs";
 import { EventRuntimeStore } from "./event-runtime-store.js";
 import { getDefaultEventRuntimeHost } from "./event-runtime-host.js";
+import {
+  currentHostHooksV2WorkspaceBinding,
+  currentHostHooksV2WorkspaceRoot,
+  registerHostHooksV2Workspace,
+  resolveRegisteredHostHooksV2Workspace,
+  runWithHostHooksV2Workspace,
+} from "./hooks-v2-workspace-context.js";
 
 const { globToRegExp } = permissionRules;
 const { buildManagedHookEnvironment } = hookEnvironment;
+const {
+  buildExplicitHookShellInvocation,
+  issueTrustedHookSandboxContract,
+  isPathInside,
+  requireTrustedHookRoot,
+  requiresExplicitHookShell,
+  sandboxBoundaryError,
+} = hookShellCommand;
 
 const VALID_HOOK_EVENTS = new Set([
   "Setup",
   // Session
-  "PreToolUse", "PostToolUse", "Notification", "Stop", "SubagentStart", "SubagentStop",
-  "SessionResume", "SessionPause", "PostCompact", "StopFailure",
+  "PreToolUse",
+  "PostToolUse",
+  "Notification",
+  "Stop",
+  "SubagentStart",
+  "SubagentStop",
+  "SessionResume",
+  "SessionPause",
+  "PostCompact",
+  "StopFailure",
   // Auth
-  "PreCommit", "PostCommit",
+  "PreCommit",
+  "PostCommit",
   // Skill
-  "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd",
+  "UserPromptSubmit",
+  "UserPromptExpansion",
+  "SessionStart",
+  "SessionEnd",
   // Model
-  "PreCompact", "ModelSelection",
+  "PreCompact",
+  "ModelSelection",
   // Config
-  "ConfigChange", "PermissionAllow", "PermissionDeny", "PermissionRequest", "PermissionDenied",
+  "ConfigChange",
+  "PermissionAllow",
+  "PermissionDeny",
+  "PermissionRequest",
+  "PermissionDenied",
   // Timeline
   "TimelineEntry",
   // MCP
-  "McpRequest", "McpResponse", "MCPElicitation", "Elicitation", "ElicitationResult",
+  "McpRequest",
+  "McpResponse",
+  "MCPElicitation",
+  "Elicitation",
+  "ElicitationResult",
   // Task / workspace lifecycle
-  "TaskCreated", "TaskCompleted", "InstructionsLoaded", "CwdChanged",
-  "WorktreeCreate", "WorktreeRemove", "TeammateIdle",
+  "TaskCreated",
+  "TaskCompleted",
+  "InstructionsLoaded",
+  "CwdChanged",
+  "WorktreeCreate",
+  "WorktreeRemove",
+  "TeammateIdle",
   // Tool aggregate / failure / filesystem lifecycle
-  "PostToolUseFailure", "PostToolBatch", "FileChanged",
+  "PostToolUseFailure",
+  "PostToolBatch",
+  "FileChanged",
 ]);
 
 const VALID_EXECUTOR_TYPES = new Set([
@@ -137,7 +181,9 @@ function strictestDecision(results) {
 
 function hostnameMatches(hostname, pattern) {
   const host = String(hostname || "").toLowerCase();
-  const rule = String(pattern || "").trim().toLowerCase();
+  const rule = String(pattern || "")
+    .trim()
+    .toLowerCase();
   if (!host || !rule) return false;
   if (rule.startsWith("*.")) {
     const suffix = rule.slice(1);
@@ -240,12 +286,31 @@ export function resolveHookSandboxPolicy(hook = {}, managedPolicy = {}) {
   return resolved;
 }
 
+function hooksRequireWorkspaceBinding(hooks, managedPolicy) {
+  return hooks.some((hook) => {
+    if (hook.type !== "command") return false;
+    try {
+      return requiresExplicitHookShell(
+        resolveHookSandboxPolicy(hook, managedPolicy),
+      );
+    } catch {
+      // Invalid policy is fail-closed during execution and must remain so after
+      // a crash instead of recovering without workspace authority.
+      return true;
+    }
+  });
+}
+
 export function assertManagedHookPolicy(
   hook,
   context = {},
   policy = {},
   configDir = null,
+  workspaceRoot = null,
 ) {
+  // Retained for API compatibility and non-command policy growth, but never
+  // consulted as filesystem authority.
+  void context;
   if (!managedListAllows(hook.type, policy.allowedExecutors)) {
     throw managedPolicyError(
       `Hook executor is outside the managed allowlist: ${hook.type}`,
@@ -259,10 +324,7 @@ export function assertManagedHookPolicy(
       );
     }
     const executable = String(hook.command || "");
-    const commandCandidates = new Set([
-      executable,
-      path.basename(executable),
-    ]);
+    const commandCandidates = new Set([executable, path.basename(executable)]);
     if (
       Array.isArray(policy.commandAllowlist) &&
       ![...commandCandidates].some((value) =>
@@ -273,7 +335,11 @@ export function assertManagedHookPolicy(
         `Hook command is outside the managed allowlist: ${executable}`,
       );
     }
-    const cwd = hook.cwd || context.cwd || configDir || process.cwd();
+    // The event context is payload, not workspace authority. Keep this
+    // selection identical to _execCommand so a forged context.cwd cannot make
+    // the managed-root check approve a different directory than the one the
+    // Broker will actually execute in.
+    const cwd = hook.cwd || configDir || workspaceRoot || process.cwd();
     if (!isInsideManagedRoot(cwd, policy.workspaceRoots)) {
       throw managedPolicyError(
         `Hook working directory is outside managed workspace roots: ${cwd}`,
@@ -315,7 +381,11 @@ export function fileChangedHookMatches(hook, context = {}) {
     hook?.globs ?? hook?.paths ?? hook?.glob ?? hook?.if ?? null;
   if (configured == null) return true;
   const patterns = (Array.isArray(configured) ? configured : [configured])
-    .map((value) => String(value || "").trim().replace(/\\/g, "/"))
+    .map((value) =>
+      String(value || "")
+        .trim()
+        .replace(/\\/g, "/"),
+    )
     .filter(Boolean);
   if (patterns.length === 0) return true;
 
@@ -392,6 +462,17 @@ class HooksV2Runtime extends EventEmitter {
   constructor(configDir, options = {}) {
     super();
     this.configDir = configDir;
+    // Both values are host constructor inputs. Hook definitions may select a
+    // cwd inside this root, but can never replace the writable root used to
+    // issue a Linux one-shot execution contract.
+    const configuredWorkspaceRoot = options.workspaceRoot || configDir || null;
+    this.workspaceBinding =
+      typeof configuredWorkspaceRoot === "string" &&
+      path.isAbsolute(configuredWorkspaceRoot)
+        ? registerHostHooksV2Workspace(configuredWorkspaceRoot)
+        : null;
+    this.workspaceRoot =
+      this.workspaceBinding?.workspaceRoot || configuredWorkspaceRoot;
     this.durableStore = options.durableStore || null;
     this.durableOwner =
       options.durableOwner ||
@@ -457,14 +538,18 @@ class HooksV2Runtime extends EventEmitter {
       const config = JSON.parse(content);
       this.hooks.clear();
 
-      const hookDefs = Array.isArray(config) ? config : (config.hooks || []);
+      const hookDefs = Array.isArray(config) ? config : config.hooks || [];
       for (const def of hookDefs) {
         if (!VALID_HOOK_EVENTS.has(def.event)) {
-          process.emitWarning(`[hooks-v2] Unknown event type: ${def.event}, skipping`);
+          process.emitWarning(
+            `[hooks-v2] Unknown event type: ${def.event}, skipping`,
+          );
           continue;
         }
         if (!VALID_EXECUTOR_TYPES.has(def.type)) {
-          process.emitWarning(`[hooks-v2] Unknown executor type: ${def.type} for ${def.event}, skipping`);
+          process.emitWarning(
+            `[hooks-v2] Unknown executor type: ${def.type} for ${def.event}, skipping`,
+          );
           continue;
         }
         const id = def.id || crypto.randomUUID();
@@ -472,7 +557,10 @@ class HooksV2Runtime extends EventEmitter {
         this.hooks.get(def.event).push({ id, ...def });
       }
       this._loaded = true;
-      this.emit("loaded", { count: hookDefs.length, events: Array.from(this.hooks.keys()) });
+      this.emit("loaded", {
+        count: hookDefs.length,
+        events: Array.from(this.hooks.keys()),
+      });
     } catch (e) {
       if (e.code !== "ENOENT") {
         this.emit("load:error", e);
@@ -484,8 +572,10 @@ class HooksV2Runtime extends EventEmitter {
    * Register a hook programmatically
    */
   registerHook(def) {
-    if (!VALID_HOOK_EVENTS.has(def.event)) throw new Error(`Invalid event: ${def.event}`);
-    if (!VALID_EXECUTOR_TYPES.has(def.type)) throw new Error(`Invalid executor type: ${def.type}`);
+    if (!VALID_HOOK_EVENTS.has(def.event))
+      throw new Error(`Invalid event: ${def.event}`);
+    if (!VALID_EXECUTOR_TYPES.has(def.type))
+      throw new Error(`Invalid executor type: ${def.type}`);
     const contract = HOOK_EVENT_CONTRACTS[def.event];
     if (!contract.allowedExecutors.includes(def.type)) {
       throw new Error(
@@ -501,7 +591,7 @@ class HooksV2Runtime extends EventEmitter {
 
   unregisterHook(id) {
     for (const [event, hooks] of this.hooks.entries()) {
-      const idx = hooks.findIndex(h => h.id === id);
+      const idx = hooks.findIndex((h) => h.id === id);
       if (idx >= 0) {
         hooks.splice(idx, 1);
         return true;
@@ -534,22 +624,34 @@ class HooksV2Runtime extends EventEmitter {
       (max, hook) => Math.max(max, Number(hook?.timeoutMs) || 30000),
       0,
     );
+    const durableWorkspaceBinding =
+      this.workspaceBinding || currentHostHooksV2WorkspaceBinding();
+    const durableWorkspaceBindingRequired = hooksRequireWorkspaceBinding(
+      hooks,
+      this.managedPolicy,
+    );
     const durableRecord =
       this.durableStore && options.skipDurable !== true
-      ? this.durableStore.enqueueInbox(
-          {
-            runtime_type: "hooks.v2",
-            requiresHandler: true,
-            event: eventName,
-            context,
-          },
-          {
-            id: context.event_id || context.eventId || null,
-            claimOwner: this.durableOwner,
-            leaseMs: longestHookTimeout + this.durableRecoveryBufferMs,
-          },
-        )
-      : null;
+        ? this.durableStore.enqueueInbox(
+            {
+              runtime_type: "hooks.v2",
+              requiresHandler: true,
+              event: eventName,
+              context,
+            },
+            {
+              id: context.event_id || context.eventId || null,
+              metadata: {
+                hooksV2WorkspaceBindingId:
+                  durableWorkspaceBinding?.bindingId || null,
+                hooksV2WorkspaceBindingRequired:
+                  durableWorkspaceBindingRequired,
+              },
+              claimOwner: this.durableOwner,
+              leaseMs: longestHookTimeout + this.durableRecoveryBufferMs,
+            },
+          )
+        : null;
     if (durableRecord?.duplicate) {
       if (durableRecord.status === "done" && durableRecord.result) {
         return { ...durableRecord.result, duplicate: true };
@@ -577,7 +679,13 @@ class HooksV2Runtime extends EventEmitter {
     const runOne = async (hook) => {
       const execId = crypto.randomUUID();
       const start = Date.now();
-      const record = { execId, hookId: hook.id, event: eventName, type: hook.type, startedAt: new Date() };
+      const record = {
+        execId,
+        hookId: hook.id,
+        event: eventName,
+        type: hook.type,
+        startedAt: new Date(),
+      };
 
       try {
         assertManagedHookPolicy(
@@ -585,6 +693,7 @@ class HooksV2Runtime extends EventEmitter {
           context,
           this.managedPolicy,
           this.configDir,
+          this.workspaceRoot || currentHostHooksV2WorkspaceRoot(),
         );
         let result;
         switch (hook.type) {
@@ -629,9 +738,10 @@ class HooksV2Runtime extends EventEmitter {
       this.executionLog.push(record);
       return record;
     };
-    const results = options.parallel === false
-      ? []
-      : await Promise.all(uniqueHooks.map(runOne));
+    const results =
+      options.parallel === false
+        ? []
+        : await Promise.all(uniqueHooks.map(runOne));
     if (options.parallel === false) {
       for (const hook of uniqueHooks) results.push(await runOne(hook));
     }
@@ -643,8 +753,7 @@ class HooksV2Runtime extends EventEmitter {
     const blocked = decision === "block";
     const blockingResult = blocking[0]?.result || null;
     const outcome = {
-      success:
-        !blocked && results.every((record) => record.status !== "error"),
+      success: !blocked && results.every((record) => record.status !== "error"),
       results,
       blocked,
       requiresApproval: decision === "ask",
@@ -689,24 +798,74 @@ class HooksV2Runtime extends EventEmitter {
       throw new Error("command hook requires a command");
     }
     const budget = hookBudget(hook);
-    const sandboxPolicy = resolveHookSandboxPolicy(
-      hook,
-      this.managedPolicy,
-    );
+    const sandboxPolicy = resolveHookSandboxPolicy(hook, this.managedPolicy);
+    const requiresContract = requiresExplicitHookShell(sandboxPolicy);
+    const trustedRootSource =
+      this.workspaceRoot || currentHostHooksV2WorkspaceRoot();
+    const trustedRoot = requiresContract
+      ? requireTrustedHookRoot(
+          trustedRootSource,
+          "Hooks v2 trusted workspace root",
+        )
+      : null;
+    const commandCwd =
+      hook.cwd || this.configDir || trustedRoot || process.cwd();
+    if (requiresContract) {
+      requireTrustedHookRoot(commandCwd, "Hooks v2 hook working directory");
+      if (!isPathInside(trustedRoot, commandCwd)) {
+        throw sandboxBoundaryError(
+          "Hooks v2 hook working directory escapes the trusted workspace root",
+        );
+      }
+    }
+    const invocation =
+      requiresContract && hook.shell === true
+        ? buildExplicitHookShellInvocation(hook.command, {
+            args: hook.args || [],
+          })
+        : {
+            file: hook.command,
+            argv: hook.args || [],
+          };
+    const commandOptions = {
+      cwd: commandCwd,
+      env: buildHookEnvironment(hook, this.managedPolicy),
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: budget.timeoutMs,
+      shell: requiresContract ? false : hook.shell === true,
+      origin: "hook",
+      scope: "hook",
+      policy: "allow",
+      hookName: hook.id,
+      ...(sandboxPolicy ? { sandboxPolicy } : {}),
+    };
+    const sandboxExecutionContract = requiresContract
+      ? issueTrustedHookSandboxContract({
+          issuer:
+            this.executionBroker.issueLinuxWorkspaceSandboxExecutionContract,
+          receiver: this.executionBroker,
+          file: invocation.file,
+          args: invocation.argv,
+          options: commandOptions,
+          trustedRoot,
+          label: "trusted Hooks v2 sandbox contract issuance failed",
+        })
+      : null;
+    if (
+      process.platform === "linux" &&
+      requiresContract &&
+      !sandboxExecutionContract
+    ) {
+      throw sandboxBoundaryError(
+        "trusted Linux Hooks v2 sandbox contract could not be issued",
+      );
+    }
     const child = await this.executionBroker.spawn(
-      hook.command,
-      hook.args || [],
+      invocation.file,
+      invocation.argv,
       {
-        cwd: hook.cwd || this.configDir || process.cwd(),
-        env: buildHookEnvironment(hook, this.managedPolicy),
-        stdio: ["pipe", "pipe", "pipe"],
-        timeout: budget.timeoutMs,
-        shell: hook.shell === true,
-        origin: "hook",
-        scope: "hook",
-        policy: "allow",
-        hookName: hook.id,
-        ...(sandboxPolicy ? { sandboxPolicy } : {}),
+        ...commandOptions,
+        ...(sandboxExecutionContract ? { sandboxExecutionContract } : {}),
       },
     );
     const payload = JSON.stringify({
@@ -716,14 +875,19 @@ class HooksV2Runtime extends EventEmitter {
     });
     child.stdin?.end(payload);
     return new Promise((resolve, reject) => {
-      let stdout = "", stderr = "";
-      child.stdout?.on("data", d => stdout += d);
-      child.stderr?.on("data", d => stderr += d);
+      let stdout = "",
+        stderr = "";
+      child.stdout?.on("data", (d) => (stdout += d));
+      child.stderr?.on("data", (d) => (stderr += d));
       child.on("error", reject);
       child.on("exit", (code) => {
         if (code === 0) {
           let parsed = {};
-          try { parsed = JSON.parse(stdout); } catch { parsed = { raw: stdout }; }
+          try {
+            parsed = JSON.parse(stdout);
+          } catch {
+            parsed = { raw: stdout };
+          }
           resolve({ ...parsed, exitCode: code, stderr });
         } else {
           reject(new Error(`Hook command failed with exit ${code}: ${stderr}`));
@@ -763,7 +927,10 @@ class HooksV2Runtime extends EventEmitter {
       const res = await this.fetchImpl(target, {
         method,
         headers,
-        body: method !== "GET" ? JSON.stringify({ event: hook.event, context }) : undefined,
+        body:
+          method !== "GET"
+            ? JSON.stringify({ event: hook.event, context })
+            : undefined,
         signal: controller.signal,
       });
       clearTimeout(timer);
@@ -782,10 +949,7 @@ class HooksV2Runtime extends EventEmitter {
       throw new Error("prompt hook executor is not configured");
     }
     const budget = hookBudget(hook);
-    const sandboxPolicy = resolveHookSandboxPolicy(
-      hook,
-      this.managedPolicy,
-    );
+    const sandboxPolicy = resolveHookSandboxPolicy(hook, this.managedPolicy);
     return executeWithHookTimeout("prompt", budget, (signal) =>
       executor({
         hook,
@@ -805,10 +969,7 @@ class HooksV2Runtime extends EventEmitter {
       throw new Error("agent hook executor is not configured");
     }
     const budget = hookBudget(hook);
-    const sandboxPolicy = resolveHookSandboxPolicy(
-      hook,
-      this.managedPolicy,
-    );
+    const sandboxPolicy = resolveHookSandboxPolicy(hook, this.managedPolicy);
     return executeWithHookTimeout("agent", budget, (signal) =>
       executor({
         hook,
@@ -858,10 +1019,7 @@ class HooksV2Runtime extends EventEmitter {
       }
     }
     const budget = hookBudget(hook);
-    const sandboxPolicy = resolveHookSandboxPolicy(
-      hook,
-      this.managedPolicy,
-    );
+    const sandboxPolicy = resolveHookSandboxPolicy(hook, this.managedPolicy);
     return executeWithHookTimeout("mcp_tool", budget, (signal) =>
       executor({
         server: hook.server,
@@ -889,7 +1047,12 @@ class HooksV2Runtime extends EventEmitter {
   getHookRegistry() {
     const registry = {};
     for (const [event, hooks] of this.hooks.entries()) {
-      registry[event] = hooks.map(h => ({ id: h.id, type: h.type, description: h.description, blocking: h.blocking }));
+      registry[event] = hooks.map((h) => ({
+        id: h.id,
+        type: h.type,
+        description: h.description,
+        blocking: h.blocking,
+      }));
     }
     return registry;
   }
@@ -912,12 +1075,48 @@ const hooksRuntime = new HooksV2Runtime(undefined, {
       ? new EventRuntimeStore()
       : null),
 });
-defaultEventRuntimeHost?.registerHandler(
-  (event) =>
-    hooksRuntime.executeHooks(event.event, event.context || {}, {
+broker._setHooksEventSink(hooksRuntime);
+
+export async function executeRecoveredHooksV2Event(
+  runtime,
+  event,
+  record = {},
+) {
+  const bindingId = record?.metadata?.hooksV2WorkspaceBindingId || null;
+  const bindingRequired =
+    record?.metadata?.hooksV2WorkspaceBindingRequired === true ||
+    hooksRequireWorkspaceBinding(
+      runtime?.hooks?.get?.(event?.event) || [],
+      runtime?.managedPolicy || {},
+    );
+  if (!bindingId) {
+    if (bindingRequired) {
+      throw sandboxBoundaryError(
+        "durable Hooks v2 recovery requires a trusted host workspace binding",
+      );
+    }
+    return runtime.executeHooks(event.event, event.context || {}, {
+      skipDurable: true,
+      recovered: true,
+    });
+  }
+
+  const binding = resolveRegisteredHostHooksV2Workspace(bindingId);
+  if (!binding) {
+    throw sandboxBoundaryError(
+      "durable Hooks v2 workspace binding is not registered by this host",
+    );
+  }
+  return runWithHostHooksV2Workspace(binding.workspaceRoot, () =>
+    runtime.executeHooks(event.event, event.context || {}, {
       skipDurable: true,
       recovered: true,
     }),
+  );
+}
+
+defaultEventRuntimeHost?.registerHandler(
+  (event, record) => executeRecoveredHooksV2Event(hooksRuntime, event, record),
   { queue: "inbox", type: "hooks.v2" },
 );
 export default hooksRuntime;