chainlesschain 0.162.179 → 0.162.181

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

@@ -1,5 +1,6 @@
 /**
- * Hooks v2 System — M3-1: 完整18事件schema + 5种executor类型
+ * Hooks v2 System — 40-event schema + 5 public executor types
+ * (plus trusted programmatic `js` compatibility handlers).
  * 对应文档 §2.3
  *
  * 支持的18种生命周期事件:
@@ -24,9 +25,14 @@ import crypto from "node:crypto";
 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 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 VALID_HOOK_EVENTS = new Set([
   "Setup",
   // Session
@@ -106,20 +112,6 @@ export const HOOK_EVENT_CONTRACTS = Object.freeze(
   ),
 );
 
-const SAFE_ENV_KEYS = Object.freeze([
-  "PATH",
-  "PATHEXT",
-  "SystemRoot",
-  "WINDIR",
-  "COMSPEC",
-  "TMP",
-  "TEMP",
-  "TMPDIR",
-  "LANG",
-  "LC_ALL",
-  "HOME",
-  "USERPROFILE",
-]);
 const DECISION_RANK = Object.freeze({
   continue: 0,
   allow: 1,
@@ -154,26 +146,209 @@ function hostnameMatches(hostname, pattern) {
   return host === rule;
 }
 
-function buildHookEnvironment(hook, policy) {
-  const env = {};
-  for (const key of SAFE_ENV_KEYS) {
-    if (process.env[key] != null) env[key] = process.env[key];
+function managedListAllows(value, configured) {
+  if (!Array.isArray(configured)) return true;
+  const candidate = String(value || "");
+  return configured.some((entry) => {
+    const pattern = String(entry || "").trim();
+    if (!pattern) return false;
+    if (pattern === "*") return true;
+    const expression = globToRegExp(
+      process.platform === "win32" ? pattern.toLowerCase() : pattern,
+    );
+    return expression.test(
+      process.platform === "win32" ? candidate.toLowerCase() : candidate,
+    );
+  });
+}
+
+function isInsideManagedRoot(candidate, roots) {
+  if (!Array.isArray(roots)) return true;
+  const resolved = path.resolve(candidate);
+  return roots.some((root) => {
+    const managedRoot = path.resolve(String(root));
+    const relative = path.relative(managedRoot, resolved);
+    return (
+      relative === "" ||
+      (!relative.startsWith("..") && !path.isAbsolute(relative))
+    );
+  });
+}
+
+function managedPolicyError(message) {
+  const error = new Error(message);
+  error.code = "CC_HOOK_MANAGED_POLICY_DENIED";
+  return error;
+}
+
+/**
+ * Merge the administrator policy with a hook's own requested sandbox. Managed
+ * settings may strengthen a hook but a hook cannot remove managed boundaries.
+ * Boundary identifiers are intentionally left for ProcessExecutionBroker to
+ * validate so every external-process caller gets the same stable contract.
+ */
+export function resolveHookSandboxPolicy(hook = {}, managedPolicy = {}) {
+  const hookPolicy = hook.sandboxPolicy;
+  const administratorPolicy = managedPolicy.sandboxPolicy;
+  for (const [label, value] of [
+    ["hook sandboxPolicy", hookPolicy],
+    ["managed hook sandboxPolicy", administratorPolicy],
+  ]) {
+    if (
+      value !== undefined &&
+      (value === null || typeof value !== "object" || Array.isArray(value))
+    ) {
+      throw managedPolicyError(`${label} must be an object`);
+    }
   }
-  const managed = new Set(
-    (policy.environmentAllowlist || []).map((key) => String(key)),
-  );
-  const requested = new Set(
-    (hook.environmentAllowlist || hook.envAllowlist || []).map((key) =>
-      String(key),
-    ),
-  );
-  for (const key of requested) {
-    if (!managed.has(key) || process.env[key] == null) continue;
-    env[key] = process.env[key];
+
+  const requiredBoundaries = [];
+  for (const [label, value] of [
+    ["managed requiredBoundaries", managedPolicy.requiredBoundaries],
+    [
+      "managed sandboxPolicy.requiredBoundaries",
+      administratorPolicy?.requiredBoundaries,
+    ],
+    ["hook requiredBoundaries", hook.requiredBoundaries],
+    ["hook sandboxPolicy.requiredBoundaries", hookPolicy?.requiredBoundaries],
+  ]) {
+    if (value === undefined) continue;
+    if (!Array.isArray(value)) {
+      throw managedPolicyError(`${label} must be an array`);
+    }
+    for (const boundary of value) {
+      if (!requiredBoundaries.includes(boundary)) {
+        requiredBoundaries.push(boundary);
+      }
+    }
+  }
+
+  const configured =
+    hookPolicy !== undefined ||
+    administratorPolicy !== undefined ||
+    hook.requiredBoundaries !== undefined ||
+    managedPolicy.requiredBoundaries !== undefined;
+  if (!configured) return null;
+  const resolved = {
+    ...(hookPolicy || {}),
+    ...(administratorPolicy || {}),
+  };
+  delete resolved.requiredBoundaries;
+  if (requiredBoundaries.length > 0) {
+    resolved.requiredBoundaries = requiredBoundaries;
+  }
+  return resolved;
+}
+
+export function assertManagedHookPolicy(
+  hook,
+  context = {},
+  policy = {},
+  configDir = null,
+) {
+  if (!managedListAllows(hook.type, policy.allowedExecutors)) {
+    throw managedPolicyError(
+      `Hook executor is outside the managed allowlist: ${hook.type}`,
+    );
+  }
+
+  if (hook.type === "command") {
+    if (hook.shell === true && policy.allowShell !== true) {
+      throw managedPolicyError(
+        "Shell-mode command hooks are disabled by managed policy",
+      );
+    }
+    const executable = String(hook.command || "");
+    const commandCandidates = new Set([
+      executable,
+      path.basename(executable),
+    ]);
+    if (
+      Array.isArray(policy.commandAllowlist) &&
+      ![...commandCandidates].some((value) =>
+        managedListAllows(value, policy.commandAllowlist),
+      )
+    ) {
+      throw managedPolicyError(
+        `Hook command is outside the managed allowlist: ${executable}`,
+      );
+    }
+    const cwd = hook.cwd || context.cwd || configDir || process.cwd();
+    if (!isInsideManagedRoot(cwd, policy.workspaceRoots)) {
+      throw managedPolicyError(
+        `Hook working directory is outside managed workspace roots: ${cwd}`,
+      );
+    }
+  }
+
+  if (hook.type === "mcp_tool") {
+    const target = `${hook.server || ""}/${hook.tool || ""}`;
+    if (!managedListAllows(target, policy.mcpToolAllowlist)) {
+      throw managedPolicyError(
+        `MCP hook target is outside the managed allowlist: ${target}`,
+      );
+    }
+  }
+
+  if (
+    hook.type === "agent" &&
+    hook.agentName &&
+    !managedListAllows(hook.agentName, policy.agentAllowlist)
+  ) {
+    throw managedPolicyError(
+      `Hook agent is outside the managed allowlist: ${hook.agentName}`,
+    );
+  }
+  if (
+    hook.type === "agent" &&
+    hook.skillName &&
+    !managedListAllows(hook.skillName, policy.skillAllowlist)
+  ) {
+    throw managedPolicyError(
+      `Hook skill is outside the managed allowlist: ${hook.skillName}`,
+    );
+  }
+}
+
+export function fileChangedHookMatches(hook, context = {}) {
+  const configured =
+    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, "/"))
+    .filter(Boolean);
+  if (patterns.length === 0) return true;
+
+  const rawPath = String(context.path || "").replace(/\\/g, "/");
+  if (!rawPath) return false;
+  const candidates = new Set([rawPath.replace(/^\.\//, "")]);
+  if (path.isAbsolute(rawPath)) {
+    const relative = path
+      .relative(context.cwd || process.cwd(), rawPath)
+      .replace(/\\/g, "/");
+    if (relative && !relative.startsWith("../")) candidates.add(relative);
   }
-  env.CC_HOOK_EVENT = hook.event;
-  env.CC_HOOK_SCHEMA_VERSION = String(HOOK_EVENT_SCHEMA_VERSION);
-  return env;
+  const caseInsensitive = process.platform === "win32";
+  return patterns.some((pattern) => {
+    const normalizedPattern = pattern.replace(/^\.\//, "");
+    const expression = globToRegExp(
+      caseInsensitive ? normalizedPattern.toLowerCase() : normalizedPattern,
+    );
+    return [...candidates].some((candidate) =>
+      expression.test(caseInsensitive ? candidate.toLowerCase() : candidate),
+    );
+  });
+}
+
+function buildHookEnvironment(hook, policy) {
+  return buildManagedHookEnvironment({
+    managedAllowlist: policy.environmentAllowlist,
+    requestedAllowlist: hook.environmentAllowlist || hook.envAllowlist,
+    values: {
+      CC_HOOK_EVENT: hook.event,
+      CC_HOOK_SCHEMA_VERSION: HOOK_EVENT_SCHEMA_VERSION,
+    },
+  });
 }
 
 function hookBudget(hook) {
@@ -190,6 +365,29 @@ function hookBudget(hook) {
   });
 }
 
+async function executeWithHookTimeout(label, budget, executor) {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      const error = new Error(
+        `${label} hook exceeded its ${budget.timeoutMs}ms budget`,
+      );
+      error.code = "CC_HOOK_BUDGET_EXCEEDED";
+      reject(error);
+    }, budget.timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      Promise.resolve().then(() => executor(controller.signal)),
+      timeout,
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 class HooksV2Runtime extends EventEmitter {
   constructor(configDir, options = {}) {
     super();
@@ -210,9 +408,15 @@ class HooksV2Runtime extends EventEmitter {
       ...(options.promptExecutor ? { prompt: options.promptExecutor } : {}),
       ...(options.agentExecutor ? { agent: options.agentExecutor } : {}),
     };
+    this.mcpAuthorizer =
+      typeof options.mcpAuthorizer === "function"
+        ? options.mcpAuthorizer
+        : null;
     this.managedPolicy = {
       httpAllowlist: [],
       environmentAllowlist: [],
+      allowShell: false,
+      requireMcpAuthorization: true,
       ...(options.managedPolicy || {}),
     };
     this.hooks = new Map(); // eventName -> HookDefinition[]
@@ -243,6 +447,8 @@ class HooksV2Runtime extends EventEmitter {
    * @property {boolean} [blocking] - default false
    * @property {string[]} [if] - conditional matchers
    * @property {string} [description]
+   * @property {{profile?:string, requiredBoundaries?:string[]}} [sandboxPolicy]
+   * @property {string[]} [requiredBoundaries]
    */
 
   async loadHooks(hooksPath) {
@@ -315,7 +521,10 @@ class HooksV2Runtime extends EventEmitter {
       throw new Error(`Invalid hook event: ${eventName}`);
     }
 
-    const hooks = this.hooks.get(eventName) || [];
+    const hooks = (this.hooks.get(eventName) || []).filter(
+      (hook) =>
+        eventName !== "FileChanged" || fileChangedHookMatches(hook, context),
+    );
     // Reserve the durable record for the inline producer before executing any
     // hook. A process-level EventRuntimeHost may observe the same store, but it
     // cannot reclaim this record until the longest declared hook timeout plus
@@ -371,6 +580,12 @@ class HooksV2Runtime extends EventEmitter {
       const record = { execId, hookId: hook.id, event: eventName, type: hook.type, startedAt: new Date() };
 
       try {
+        assertManagedHookPolicy(
+          hook,
+          context,
+          this.managedPolicy,
+          this.configDir,
+        );
         let result;
         switch (hook.type) {
           case "command":
@@ -474,6 +689,10 @@ class HooksV2Runtime extends EventEmitter {
       throw new Error("command hook requires a command");
     }
     const budget = hookBudget(hook);
+    const sandboxPolicy = resolveHookSandboxPolicy(
+      hook,
+      this.managedPolicy,
+    );
     const child = await this.executionBroker.spawn(
       hook.command,
       hook.args || [],
@@ -487,6 +706,7 @@ class HooksV2Runtime extends EventEmitter {
         scope: "hook",
         policy: "allow",
         hookName: hook.id,
+        ...(sandboxPolicy ? { sandboxPolicy } : {}),
       },
     );
     const payload = JSON.stringify({
@@ -561,12 +781,22 @@ class HooksV2Runtime extends EventEmitter {
     if (typeof executor !== "function") {
       throw new Error("prompt hook executor is not configured");
     }
-    return executor({
+    const budget = hookBudget(hook);
+    const sandboxPolicy = resolveHookSandboxPolicy(
       hook,
-      prompt: expanded,
-      context,
-      budget: hookBudget(hook),
-    });
+      this.managedPolicy,
+    );
+    return executeWithHookTimeout("prompt", budget, (signal) =>
+      executor({
+        hook,
+        prompt: expanded,
+        context,
+        budget,
+        signal,
+        managedPolicy: this.managedPolicy,
+        ...(sandboxPolicy ? { sandboxPolicy } : {}),
+      }),
+    );
   }
 
   async _execAgent(hook, context) {
@@ -574,13 +804,23 @@ class HooksV2Runtime extends EventEmitter {
     if (typeof executor !== "function") {
       throw new Error("agent hook executor is not configured");
     }
-    return executor({
+    const budget = hookBudget(hook);
+    const sandboxPolicy = resolveHookSandboxPolicy(
       hook,
-      agentName: hook.agentName || null,
-      skillName: hook.skillName || null,
-      context,
-      budget: hookBudget(hook),
-    });
+      this.managedPolicy,
+    );
+    return executeWithHookTimeout("agent", budget, (signal) =>
+      executor({
+        hook,
+        agentName: hook.agentName || null,
+        skillName: hook.skillName || null,
+        context,
+        budget,
+        signal,
+        managedPolicy: this.managedPolicy,
+        ...(sandboxPolicy ? { sandboxPolicy } : {}),
+      }),
+    );
   }
 
   async _execMcpTool(hook, context) {
@@ -591,14 +831,51 @@ class HooksV2Runtime extends EventEmitter {
     if (!hook.server || !hook.tool) {
       throw new Error("mcp_tool hook requires server and tool");
     }
-    return executor({
-      server: hook.server,
-      tool: hook.tool,
-      arguments: hook.arguments || context,
-      context,
+    let permission = null;
+    if (this.managedPolicy.requireMcpAuthorization !== false) {
+      if (!this.mcpAuthorizer) {
+        throw managedPolicyError(
+          "MCP hook requires the shared MCP permission authorizer",
+        );
+      }
+      permission = await this.mcpAuthorizer({
+        server: hook.server,
+        tool: hook.tool,
+        arguments: hook.arguments || context,
+        context,
+        hook,
+      });
+      const decision = String(permission?.decision || "").toLowerCase();
+      if (
+        permission !== true &&
+        permission?.allowed !== true &&
+        decision !== "allow" &&
+        decision !== "approve"
+      ) {
+        throw managedPolicyError(
+          `MCP hook permission denied: ${hook.server}/${hook.tool}`,
+        );
+      }
+    }
+    const budget = hookBudget(hook);
+    const sandboxPolicy = resolveHookSandboxPolicy(
       hook,
-      budget: hookBudget(hook),
-    });
+      this.managedPolicy,
+    );
+    return executeWithHookTimeout("mcp_tool", budget, (signal) =>
+      executor({
+        server: hook.server,
+        tool: hook.tool,
+        arguments: hook.arguments || context,
+        context,
+        hook,
+        budget,
+        signal,
+        permission,
+        managedPolicy: this.managedPolicy,
+        ...(sandboxPolicy ? { sandboxPolicy } : {}),
+      }),
+    );
   }
 
   async _execJs(hook, context) {

package/src/lib/interaction-adapter.js

@@ -16,6 +16,10 @@ import {
 import { createAbortError } from "./abort-utils.js";
 import { emitHooksV2Event } from "./hooks-v2-producers.js";
 import { verifyApprovalBinding } from "./agent-authority.js";
+import {
+  normalizeInteractionBinding,
+  sameInteractionBinding,
+} from "./interaction-binding.js";
 import { createEnvelope } from "@chainlesschain/session-core";
 
 // Phase 5: parallel service-envelope emission. Map WS agent-handler event
@@ -128,6 +132,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     // this WS session instead of leaking across sessions via the process-
     // global default tracker.
     this._sequenceTracker = new CodingAgentSequenceTracker();
+    this._questionSequence = 0;
     // Phase 5: parallel service-envelope emission. Opt-in (default off) so
     // legacy callers that count ws.send invocations stay green.
     this.enablePhase5Envelopes = options.enablePhase5Envelopes === true;
@@ -175,6 +180,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
         // routed / argument-tampered verdict and is rejected in _resolvePending.
         // null (the default for plain questions) → no binding check, unchanged.
         binding: options.binding || null,
+        bindingType: options.bindingType || null,
       });
 
       this._sendWs({
@@ -274,6 +280,12 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
           }
         : {}),
     };
+    const binding = normalizeInteractionBinding({
+      sessionId: this.sessionId,
+      turnId: normalizedTurnId,
+      toolUseId: normalizedToolUseId,
+      sequence: ++this._questionSequence,
+    });
 
     return this._request(
       {
@@ -295,10 +307,13 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
               tool_use_id: normalizedToolUseId,
             }
           : {}),
+        binding,
         metadata: questionMetadata,
       },
       {
         kind: "question",
+        binding,
+        bindingType: "interaction",
         ...(Number(timeoutMs) > 0 ? { timeoutMs: Number(timeoutMs) } : {}),
       },
     );
@@ -324,30 +339,48 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     requestedSchema = null,
     timeoutMs,
   } = {}) {
-    emitHooksV2Event("MCPElicitation", {
+    const hookContext = {
+      schema_version: 1,
       server: server || null,
       request_id: mcpRequestId ?? null,
       message: String(message),
       requested_schema: requestedSchema || null,
-    });
-    return this._request(
-      {
-        type: "question",
-        questionType: "elicitation",
-        question: String(message),
-        ...(requestedSchema ? { requestedSchema } : {}),
-        metadata: {
-          kind: "mcp_elicitation",
-          server: server || null,
-          requestId: mcpRequestId ?? null,
-          requestedSchema: requestedSchema || null,
+      session_id: this.sessionId || null,
+    };
+    emitHooksV2Event("MCPElicitation", hookContext);
+    emitHooksV2Event("Elicitation", hookContext);
+    try {
+      const answer = await this._request(
+        {
+          type: "question",
+          questionType: "elicitation",
+          question: String(message),
+          ...(requestedSchema ? { requestedSchema } : {}),
+          metadata: {
+            kind: "mcp_elicitation",
+            server: server || null,
+            requestId: mcpRequestId ?? null,
+            requestedSchema: requestedSchema || null,
+          },
         },
-      },
-      {
-        kind: "question",
-        ...(Number(timeoutMs) > 0 ? { timeoutMs: Number(timeoutMs) } : {}),
-      },
-    );
+        {
+          kind: "question",
+          ...(Number(timeoutMs) > 0 ? { timeoutMs: Number(timeoutMs) } : {}),
+        },
+      );
+      emitHooksV2Event("ElicitationResult", {
+        ...hookContext,
+        action: answer == null ? "cancel" : "accept",
+      });
+      return answer;
+    } catch (error) {
+      emitHooksV2Event("ElicitationResult", {
+        ...hookContext,
+        action: "cancel",
+        reason: error?.code || error?.message || "interaction_failed",
+      });
+      throw error;
+    }
   }
 
   async requestHostTool(toolName, args = {}, extra = {}) {
@@ -484,8 +517,16 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     // (fail closed) instead of the approve it claims to be, mirroring the local
     // headless approval gate. Backward-compatible: no request binding, or an
     // answer with no echoed binding, resolves exactly as before.
+    if (
+      pending.bindingType === "interaction" &&
+      !sameInteractionBinding(pending.binding, incomingBinding)
+    ) {
+      return;
+    }
+
     let effective = payload;
     if (
+      pending.bindingType !== "interaction" &&
       pending.binding &&
       incomingBinding &&
       !verifyApprovalBinding(pending.binding, incomingBinding)

package/src/lib/interaction-binding.js

@@ -0,0 +1,64 @@
+/**
+ * Transport-neutral binding for a human interaction response.
+ *
+ * The binding is intentionally plain JSON so CLI attach, WebSocket, Desktop,
+ * VS Code, JetBrains, SDK and Remote Control can echo the same value without
+ * reinterpreting it. The runtime that created the request remains authoritative
+ * and compares every field before accepting a response.
+ */
+
+function asNullableString(value) {
+  if (value === undefined || value === null || value === "") return null;
+  return String(value);
+}
+
+export function normalizeInteractionBinding(binding = {}) {
+  const source =
+    binding && typeof binding === "object" && !Array.isArray(binding)
+      ? binding
+      : {};
+  return {
+    backgroundAgentId: asNullableString(
+      source.backgroundAgentId ?? source.background_agent_id,
+    ),
+    sessionId: asNullableString(source.sessionId ?? source.session_id),
+    turnId: asNullableString(source.turnId ?? source.turn_id),
+    toolUseId: asNullableString(
+      source.toolUseId ??
+        source.tool_use_id ??
+        source.toolCallId ??
+        source.tool_call_id,
+    ),
+    sequence:
+      Number.isSafeInteger(source.sequence) && source.sequence > 0
+        ? source.sequence
+        : null,
+  };
+}
+
+export function sameInteractionBinding(left, right) {
+  const a = normalizeInteractionBinding(left);
+  const b = normalizeInteractionBinding(right);
+  return (
+    a.backgroundAgentId === b.backgroundAgentId &&
+    a.sessionId === b.sessionId &&
+    a.turnId === b.turnId &&
+    a.toolUseId === b.toolUseId &&
+    a.sequence === b.sequence
+  );
+}
+
+export function hasCompleteInteractionBinding(binding) {
+  if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+    return false;
+  }
+  const hasAny = (...keys) =>
+    keys.some((key) => Object.prototype.hasOwnProperty.call(binding, key));
+  return (
+    hasAny("backgroundAgentId", "background_agent_id") &&
+    hasAny("sessionId", "session_id") &&
+    hasAny("turnId", "turn_id") &&
+    hasAny("toolUseId", "tool_use_id", "toolCallId", "tool_call_id") &&
+    normalizeInteractionBinding(binding).sequence !== null
+  );
+}