chainlesschain 0.162.182 → 0.162.184

package/src/lib/hook-shell-command.cjs

@@ -0,0 +1,148 @@
+"use strict";
+
+const path = require("node:path");
+
+const STRONG_HOOK_BOUNDARIES = new Set(["filesystem", "network"]);
+
+function requiredHookBoundaries(sandboxPolicy) {
+  const configured = sandboxPolicy?.requiredBoundaries;
+  return Array.isArray(configured) ? configured : [];
+}
+
+function requiresExplicitHookShell(sandboxPolicy) {
+  return requiredHookBoundaries(sandboxPolicy).some((boundary) =>
+    STRONG_HOOK_BOUNDARIES.has(boundary),
+  );
+}
+
+function sandboxBoundaryError(message) {
+  const error = new Error(message);
+  error.code = "ERR_PROCESS_SANDBOX_BOUNDARY_UNSATISFIED";
+  error.sandboxFailClosed = true;
+  return error;
+}
+
+function asSandboxBoundaryError(error, prefix) {
+  if (error?.code === "ERR_PROCESS_SANDBOX_BOUNDARY_UNSATISFIED") {
+    return error;
+  }
+  const detail =
+    error && typeof error.message === "string" ? error.message : String(error);
+  return sandboxBoundaryError(`${prefix}: ${detail}`);
+}
+
+function issueTrustedHookSandboxContract({
+  issuer,
+  receiver = null,
+  file,
+  args,
+  options,
+  trustedRoot,
+  sync = false,
+  label = "trusted hook sandbox contract issuance failed",
+}) {
+  if (typeof issuer !== "function") return null;
+  try {
+    return issuer.call(
+      receiver,
+      file,
+      args,
+      options,
+      trustedRoot,
+      ...(sync ? [{ sync: true }] : []),
+    );
+  } catch (error) {
+    throw asSandboxBoundaryError(error, label);
+  }
+}
+
+function requireTrustedHookRoot(value, label = "hook working directory") {
+  if (
+    typeof value !== "string" ||
+    !value ||
+    value.includes("\0") ||
+    !path.isAbsolute(value)
+  ) {
+    throw sandboxBoundaryError(
+      `${label} must be an absolute trusted path for filesystem/network sandboxing`,
+    );
+  }
+  return path.resolve(value);
+}
+
+function isPathInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return (
+    relative === "" ||
+    (relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`) &&
+      !path.isAbsolute(relative))
+  );
+}
+
+function quotePosixShellArgument(value) {
+  const text = String(value);
+  if (text.length === 0) return "''";
+  return `'${text.replace(/'/g, `'"'"'`)}'`;
+}
+
+function quoteCmdArgument(value) {
+  const text = String(value);
+  if (text.length === 0) return '""';
+  // The command and its arguments are all hook-controlled, but quote cmd.exe
+  // metacharacters anyway so an argv entry remains one argument.
+  return `"${text
+    .replace(/"/g, '""')
+    .replace(/([&|<>^])/g, "^$1")
+    .replace(/%/g, "%%")}"`;
+}
+
+function appendShellArguments(command, args, platform) {
+  if (!Array.isArray(args) || args.length === 0) return command;
+  const quote =
+    platform === "win32" ? quoteCmdArgument : quotePosixShellArgument;
+  return `${command} ${args.map((arg) => quote(arg)).join(" ")}`;
+}
+
+/**
+ * Turn a settings-style shell command into an explicit executable + argv.
+ * This is used only when filesystem/network boundaries are requested. Keeping
+ * shell selection explicit lets the Broker bind its one-shot contract to the
+ * actual launch tuple and guarantees the child spawn itself uses shell:false.
+ */
+function buildExplicitHookShellInvocation(
+  command,
+  {
+    args = [],
+    platform = process.platform,
+    shellKind = null,
+    buildPowershellArgv = null,
+    powershellOptions = {},
+  } = {},
+) {
+  const rendered = appendShellArguments(String(command), args, platform);
+  if (
+    (shellKind === "powershell" || shellKind === "pwsh") &&
+    typeof buildPowershellArgv === "function"
+  ) {
+    return buildPowershellArgv(rendered, shellKind, powershellOptions);
+  }
+  if (platform === "win32") {
+    return {
+      file: process.env.ComSpec || "cmd.exe",
+      argv: ["/d", "/s", "/c", rendered],
+    };
+  }
+  return { file: "/bin/sh", argv: ["-c", rendered] };
+}
+
+module.exports = {
+  buildExplicitHookShellInvocation,
+  issueTrustedHookSandboxContract,
+  isPathInside,
+  requireTrustedHookRoot,
+  requiredHookBoundaries,
+  requiresExplicitHookShell,
+  asSandboxBoundaryError,
+  sandboxBoundaryError,
+};

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

@@ -26,35 +26,72 @@ 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";
 
 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 +174,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);
@@ -259,10 +298,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) =>
@@ -315,7 +351,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 +432,10 @@ 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.
+    this.workspaceRoot = options.workspaceRoot || configDir || null;
     this.durableStore = options.durableStore || null;
     this.durableOwner =
       options.durableOwner ||
@@ -457,14 +501,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 +520,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 +535,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 +554,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;
@@ -536,20 +589,20 @@ class HooksV2Runtime extends EventEmitter {
     );
     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,
+              claimOwner: this.durableOwner,
+              leaseMs: longestHookTimeout + this.durableRecoveryBufferMs,
+            },
+          )
+        : null;
     if (durableRecord?.duplicate) {
       if (durableRecord.status === "done" && durableRecord.result) {
         return { ...durableRecord.result, duplicate: true };
@@ -577,7 +630,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(
@@ -629,9 +688,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 +703,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 +748,72 @@ 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 trustedRoot = requiresContract
+      ? requireTrustedHookRoot(
+          this.workspaceRoot,
+          "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 +823,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 +875,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 +897,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 +917,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 +967,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 +995,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;
   }

package/src/lib/jsonl-session-store.js

@@ -16,6 +16,8 @@ export {
   appendAssistantMessage,
   appendToolCall,
   appendToolCallCompact,
+  appendLlmRetryCompact,
+  MAX_COMPACT_DURATION_MS,
   appendToolResult,
   appendCompactEvent,
   readEvents,

package/src/lib/lsp/__tests__/lsp-client.test.js

@@ -100,6 +100,13 @@ describe("LSPClient handshake", () => {
 
   it("passes plugin sandbox requirements to ProcessExecutionBroker", async () => {
     const child = new FakeChild();
+    const contract = Object.freeze({ kind: "test-workspace-contract" });
+    const issueAuthority = vi
+      .spyOn(
+        executionBroker,
+        "issueLinuxWorkspaceSandboxExecutionContract",
+      )
+      .mockReturnValue(contract);
     const brokerSpawn = vi
       .spyOn(executionBroker, "spawn")
       .mockReturnValue(child);
@@ -123,8 +130,19 @@ describe("LSPClient handshake", () => {
         sandboxPolicy: {
           requiredBoundaries: ["filesystem", "network"],
         },
+        sandboxExecutionContract: contract,
       }),
     );
+    expect(issueAuthority).toHaveBeenCalledWith(
+      "fake-lsp",
+      ["--stdio"],
+      expect.objectContaining({
+        cwd: "/proj",
+        shell: false,
+        origin: "plugin:lsp",
+      }),
+      "/proj",
+    );
     expect(_deps.spawn).not.toHaveBeenCalled();
   });
 

package/src/lib/lsp/lsp-client.js

@@ -83,7 +83,7 @@ export class LSPClient extends EventEmitter {
     const spawnFn = String(this.origin || "").startsWith("plugin:")
       ? executionBroker.spawn.bind(executionBroker)
       : _deps.spawn;
-    this._child = spawnFn(spawnSpec.file, spawnSpec.args, {
+    const spawnOptions = {
       cwd: this.rootPath,
       env: { ...process.env, ...this.env },
       stdio: ["pipe", "pipe", "pipe"],
@@ -103,6 +103,17 @@ export class LSPClient extends EventEmitter {
               : {}),
           }
         : {}),
+    };
+    const sandboxExecutionContract =
+      executionBroker.issueLinuxWorkspaceSandboxExecutionContract(
+        spawnSpec.file,
+        spawnSpec.args,
+        spawnOptions,
+        this.rootPath,
+      );
+    this._child = spawnFn(spawnSpec.file, spawnSpec.args, {
+      ...spawnOptions,
+      ...(sandboxExecutionContract ? { sandboxExecutionContract } : {}),
     });
 
     this._child.on("error", (err) => {