chainlesschain 0.162.176 → 0.162.178

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

@@ -25,15 +25,17 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import broker from "./process-execution-broker/index.js";
 import { EventRuntimeStore } from "./event-runtime-store.js";
+import { getDefaultEventRuntimeHost } from "./event-runtime-host.js";
 
 const VALID_HOOK_EVENTS = new Set([
+  "Setup",
   // Session
   "PreToolUse", "PostToolUse", "Notification", "Stop", "SubagentStart", "SubagentStop",
-  "SessionResume", "SessionPause", "PostCompact",
+  "SessionResume", "SessionPause", "PostCompact", "StopFailure",
   // Auth
   "PreCommit", "PostCommit",
   // Skill
-  "UserPromptSubmit", "SessionStart", "SessionEnd",
+  "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd",
   // Model
   "PreCompact", "ModelSelection",
   // Config
@@ -41,19 +43,178 @@ const VALID_HOOK_EVENTS = new Set([
   // Timeline
   "TimelineEntry",
   // MCP
-  "McpRequest", "McpResponse", "MCPElicitation",
+  "McpRequest", "McpResponse", "MCPElicitation", "Elicitation", "ElicitationResult",
   // Task / workspace lifecycle
   "TaskCreated", "TaskCompleted", "InstructionsLoaded", "CwdChanged",
-  "WorktreeCreate", "WorktreeRemove",
+  "WorktreeCreate", "WorktreeRemove", "TeammateIdle",
+  // Tool aggregate / failure / filesystem lifecycle
+  "PostToolUseFailure", "PostToolBatch", "FileChanged",
 ]);
 
-const VALID_EXECUTOR_TYPES = new Set(["command", "http", "prompt", "agent", "js"]);
+const VALID_EXECUTOR_TYPES = new Set([
+  "command",
+  "http",
+  "mcp_tool",
+  "prompt",
+  "agent",
+  // Trusted programmatic compatibility executor. Config-loaded source text is
+  // not executed in-process.
+  "js",
+]);
+
+export const HOOK_EVENT_SCHEMA_VERSION = 1;
+const DECISION_EVENTS = new Set([
+  "Setup",
+  "PreToolUse",
+  "UserPromptSubmit",
+  "UserPromptExpansion",
+  "PermissionRequest",
+  "ModelSelection",
+  "PreCompact",
+]);
+const CONTEXT_EVENTS = new Set([
+  "Setup",
+  "UserPromptSubmit",
+  "UserPromptExpansion",
+  "SessionStart",
+  "PostCompact",
+]);
+const DEFAULT_ALLOWED_EXECUTORS = Object.freeze([
+  "command",
+  "http",
+  "mcp_tool",
+  "prompt",
+  "agent",
+  "js",
+]);
+
+export const HOOK_EVENT_CONTRACTS = Object.freeze(
+  Object.fromEntries(
+    [...VALID_HOOK_EVENTS].map((event) => [
+      event,
+      Object.freeze({
+        schemaVersion: HOOK_EVENT_SCHEMA_VERSION,
+        event,
+        allowedExecutors: DEFAULT_ALLOWED_EXECUTORS,
+        decisionCapable: DECISION_EVENTS.has(event),
+        contextCapable: CONTEXT_EVENTS.has(event),
+        blockingSemantics: DECISION_EVENTS.has(event)
+          ? "strictest:block>ask>allow>continue"
+          : "observe-only",
+      }),
+    ]),
+  ),
+);
+
+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,
+  ask: 2,
+  block: 3,
+});
+
+function normalizeDecision(value) {
+  const decision = String(value || "continue").toLowerCase();
+  return Object.hasOwn(DECISION_RANK, decision) ? decision : "continue";
+}
+
+function strictestDecision(results) {
+  let decision = "continue";
+  for (const record of results) {
+    const candidate = normalizeDecision(record?.decision);
+    if (DECISION_RANK[candidate] > DECISION_RANK[decision]) {
+      decision = candidate;
+    }
+  }
+  return decision;
+}
+
+function hostnameMatches(hostname, pattern) {
+  const host = String(hostname || "").toLowerCase();
+  const rule = String(pattern || "").trim().toLowerCase();
+  if (!host || !rule) return false;
+  if (rule.startsWith("*.")) {
+    const suffix = rule.slice(1);
+    return host.endsWith(suffix) && host.length > suffix.length;
+  }
+  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];
+  }
+  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];
+  }
+  env.CC_HOOK_EVENT = hook.event;
+  env.CC_HOOK_SCHEMA_VERSION = String(HOOK_EVENT_SCHEMA_VERSION);
+  return env;
+}
+
+function hookBudget(hook) {
+  return Object.freeze({
+    maxTurns: Math.min(10, Math.max(1, Number(hook.maxTurns) || 1)),
+    maxTokens: Math.min(
+      32768,
+      Math.max(1, Number(hook.maxTokens || hook.tokenBudget) || 4096),
+    ),
+    timeoutMs: Math.min(
+      10 * 60 * 1000,
+      Math.max(1, Number(hook.timeoutMs) || 30000),
+    ),
+  });
+}
 
 class HooksV2Runtime extends EventEmitter {
   constructor(configDir, options = {}) {
     super();
     this.configDir = configDir;
     this.durableStore = options.durableStore || null;
+    this.durableOwner =
+      options.durableOwner ||
+      `hooks-inline:${process.pid}:${crypto.randomUUID()}`;
+    this.durableRecoveryBufferMs = Math.max(
+      1000,
+      Number(options.durableRecoveryBufferMs) || 5000,
+    );
+    this.executionBroker = options.broker || broker;
+    this.fetchImpl = options.fetch || globalThis.fetch;
+    this.executors = {
+      ...(options.executors || {}),
+      ...(options.mcpExecutor ? { mcp_tool: options.mcpExecutor } : {}),
+      ...(options.promptExecutor ? { prompt: options.promptExecutor } : {}),
+      ...(options.agentExecutor ? { agent: options.agentExecutor } : {}),
+    };
+    this.managedPolicy = {
+      httpAllowlist: [],
+      environmentAllowlist: [],
+      ...(options.managedPolicy || {}),
+    };
     this.hooks = new Map(); // eventName -> HookDefinition[]
     this.executionLog = [];
     this._loaded = false;
@@ -119,6 +280,12 @@ class HooksV2Runtime extends EventEmitter {
   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}`);
+    const contract = HOOK_EVENT_CONTRACTS[def.event];
+    if (!contract.allowedExecutors.includes(def.type)) {
+      throw new Error(
+        `Executor ${def.type} is not allowed for event ${def.event}`,
+      );
+    }
     const id = def.id || crypto.randomUUID();
     const full = { id, blocking: false, timeoutMs: 30000, ...def };
     if (!this.hooks.has(def.event)) this.hooks.set(def.event, []);
@@ -149,12 +316,45 @@ class HooksV2Runtime extends EventEmitter {
     }
 
     const hooks = this.hooks.get(eventName) || [];
-    const durableRecord = this.durableStore
+    // 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
+    // a recovery buffer has elapsed. If this process dies, the expired lease
+    // becomes claimable and the host replays the event exactly once.
+    const longestHookTimeout = hooks.reduce(
+      (max, hook) => Math.max(max, Number(hook?.timeoutMs) || 30000),
+      0,
+    );
+    const durableRecord =
+      this.durableStore && options.skipDurable !== true
       ? this.durableStore.enqueueInbox(
-          { event: eventName, context },
-          { id: context.event_id || context.eventId || null },
+          {
+            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 };
+      }
+      return {
+        success: false,
+        results: [],
+        blocked: true,
+        blockingResult: null,
+        decision: "block",
+        duplicate: true,
+        pending: true,
+      };
+    }
     // Hooks are parallel by default. De-duplicate by id so a reload or layered
     // config cannot execute the same handler twice. `parallel:false` remains a
     // deterministic compatibility mode for callers that require ordering.
@@ -179,6 +379,9 @@ class HooksV2Runtime extends EventEmitter {
           case "http":
             result = await this._execHttp(hook, context);
             break;
+          case "mcp_tool":
+            result = await this._execMcpTool(hook, context);
+            break;
           case "prompt":
             result = await this._execPrompt(hook, context);
             break;
@@ -193,13 +396,18 @@ class HooksV2Runtime extends EventEmitter {
         record.durationMs = Date.now() - start;
         record.status = "success";
         record.result = result;
-        if (hook.blocking && result && result.decision === "block") record.blocked = true;
+        record.decision = normalizeDecision(result?.decision);
 
         this.emit("hook:success", record);
       } catch (err) {
         record.durationMs = Date.now() - start;
         record.status = "error";
         record.error = err.message;
+        record.decision =
+          HOOK_EVENT_CONTRACTS[eventName].decisionCapable &&
+          hook.failureMode !== "ignore"
+            ? "block"
+            : "continue";
         this.emit("hook:error", record);
       }
 
@@ -212,17 +420,42 @@ class HooksV2Runtime extends EventEmitter {
     if (options.parallel === false) {
       for (const hook of uniqueHooks) results.push(await runOne(hook));
     }
-    const blocking = results.filter((r) => r.blocked === true);
-    const blocked = blocking.length > 0;
+    const contract = HOOK_EVENT_CONTRACTS[eventName];
+    const decision = contract.decisionCapable
+      ? strictestDecision(results)
+      : "continue";
+    const blocking = results.filter((record) => record.decision === "block");
+    const blocked = decision === "block";
     const blockingResult = blocking[0]?.result || null;
-
-    const outcome = { success: !blocked, results, blocked, blockingResult };
-    if (durableRecord && !durableRecord.duplicate) {
-      this.durableStore.acknowledgeInbox(durableRecord.id, {
-        event: eventName,
-        blocked,
-        resultCount: results.length,
-      });
+    const outcome = {
+      success:
+        !blocked && results.every((record) => record.status !== "error"),
+      results,
+      blocked,
+      requiresApproval: decision === "ask",
+      decision,
+      blockingResult,
+      schemaVersion: HOOK_EVENT_SCHEMA_VERSION,
+    };
+    if (durableRecord) {
+      const settled = this.durableStore.acknowledgeInbox(
+        durableRecord.id,
+        outcome,
+        {
+          owner: durableRecord.lease?.owner,
+          fence: durableRecord.lease?.fence,
+        },
+      );
+      if (settled == null) {
+        return {
+          success: false,
+          results,
+          blocked: true,
+          blockingResult: null,
+          decision: "block",
+          leaseLost: true,
+        };
+      }
       this.durableStore.enqueueOutbox(
         { event: eventName, outcome },
         { id: `${durableRecord.id}:result` },
@@ -237,19 +470,36 @@ class HooksV2Runtime extends EventEmitter {
   }
 
   async _execCommand(hook, context) {
-    const child = await broker.spawn(
-      hook.command, hook.args || [],
+    if (!hook.command || typeof hook.command !== "string") {
+      throw new Error("command hook requires a command");
+    }
+    const budget = hookBudget(hook);
+    const child = await this.executionBroker.spawn(
+      hook.command,
+      hook.args || [],
       {
-        env: { ...process.env, CC_HOOK_EVENT: hook.event, CC_HOOK_CONTEXT: JSON.stringify(context) },
-        stdio: "pipe",
-        timeout: hook.timeoutMs,
+        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,
       },
-      { origin: "hook", hookName: hook.id, timeout: hook.timeoutMs },
     );
+    const payload = JSON.stringify({
+      schema_version: HOOK_EVENT_SCHEMA_VERSION,
+      hook_event_name: hook.event,
+      context,
+    });
+    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);
+      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 = {};
@@ -263,14 +513,36 @@ class HooksV2Runtime extends EventEmitter {
   }
 
   async _execHttp(hook, context) {
-    // Simple HTTP webhook executor
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("HTTP hook executor is unavailable");
+    }
+    const target = new URL(hook.url);
+    const allowlist = this.managedPolicy.httpAllowlist || [];
+    if (
+      target.protocol !== "https:" ||
+      !allowlist.some((pattern) => hostnameMatches(target.hostname, pattern))
+    ) {
+      const error = new Error(
+        `HTTP hook target is outside the managed HTTPS allowlist: ${target.hostname}`,
+      );
+      error.code = "CC_HOOK_HTTP_TARGET_DENIED";
+      throw error;
+    }
     const method = hook.method || "POST";
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), hook.timeoutMs || 30000);
+    const timer = setTimeout(
+      () => controller.abort(),
+      hookBudget(hook).timeoutMs,
+    );
+    const headers = { "Content-Type": "application/json" };
+    for (const [key, value] of Object.entries(hook.headers || {})) {
+      if (/^(authorization|cookie|proxy-authorization)$/i.test(key)) continue;
+      headers[key] = String(value);
+    }
     try {
-      const res = await fetch(hook.url, {
+      const res = await this.fetchImpl(target, {
         method,
-        headers: { "Content-Type": "application/json", ...(hook.headers || {}) },
+        headers,
         body: method !== "GET" ? JSON.stringify({ event: hook.event, context }) : undefined,
         signal: controller.signal,
       });
@@ -282,23 +554,58 @@ class HooksV2Runtime extends EventEmitter {
   }
 
   async _execPrompt(hook, context) {
-    // Prompt template execution - returns expanded prompt for agent prepend
     const vars = { ...context };
     let expanded = hook.template || "";
     expanded = expanded.replace(/\$\{(\w+)\}/g, (_, k) => vars[k] ?? "");
-    return { decision: "augment", prompt: expanded };
+    const executor = this.executors.prompt;
+    if (typeof executor !== "function") {
+      throw new Error("prompt hook executor is not configured");
+    }
+    return executor({
+      hook,
+      prompt: expanded,
+      context,
+      budget: hookBudget(hook),
+    });
   }
 
   async _execAgent(hook, context) {
-    // Dispatch to agent/skill - stub for full integration
-    return { decision: "delegate", agentName: hook.agentName, skillName: hook.skillName, context };
+    const executor = this.executors.agent;
+    if (typeof executor !== "function") {
+      throw new Error("agent hook executor is not configured");
+    }
+    return executor({
+      hook,
+      agentName: hook.agentName || null,
+      skillName: hook.skillName || null,
+      context,
+      budget: hookBudget(hook),
+    });
+  }
+
+  async _execMcpTool(hook, context) {
+    const executor = this.executors.mcp_tool;
+    if (typeof executor !== "function") {
+      throw new Error("MCP hook executor is not configured");
+    }
+    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,
+      hook,
+      budget: hookBudget(hook),
+    });
   }
 
   async _execJs(hook, context) {
     if (typeof hook.handler === "function") return hook.handler(context);
-    // In-process JS execution via vm (sandboxed) - config-loaded code remains
-    // disabled until the dedicated VM executor is enabled.
-    return { decision: "noop", note: "JS executor stub - context received", contextKeys: Object.keys(context) };
+    throw new Error(
+      "Config-loaded JavaScript is disabled; register a trusted function handler",
+    );
   }
 
   /** Get all registered hooks */
@@ -317,11 +624,24 @@ class HooksV2Runtime extends EventEmitter {
 }
 
 // Singleton instance
+const defaultEventRuntimeHost =
+  process.env.CC_EVENT_RUNTIME_DURABLE === "1"
+    ? getDefaultEventRuntimeHost()
+    : null;
 const hooksRuntime = new HooksV2Runtime(undefined, {
   durableStore:
-    process.env.CC_EVENT_RUNTIME_DURABLE === "1"
+    defaultEventRuntimeHost?.store ||
+    (process.env.CC_EVENT_RUNTIME_DURABLE === "1"
       ? new EventRuntimeStore()
-      : null,
+      : null),
 });
+defaultEventRuntimeHost?.registerHandler(
+  (event) =>
+    hooksRuntime.executeHooks(event.event, event.context || {}, {
+      skipDurable: true,
+      recovered: true,
+    }),
+  { queue: "inbox", type: "hooks.v2" },
+);
 export default hooksRuntime;
 export { HooksV2Runtime, VALID_HOOK_EVENTS, VALID_EXECUTOR_TYPES };

package/src/lib/host-adb-bridge.js

@@ -31,10 +31,20 @@
  *     `\n` / EOS — every parse routine strips `\r+$` first.
  */
 
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import executionBroker from "./process-execution-broker/index.js";
 
-const execFileP = promisify(execFile);
+export const _deps = {
+  execFile: (...args) => executionBroker.execFile(...args),
+};
+
+function execFileP(file, args, options) {
+  return new Promise((resolve, reject) => {
+    _deps.execFile(file, args, options, (error, stdout, stderr) => {
+      if (error) reject(error);
+      else resolve({ stdout, stderr });
+    });
+  });
+}
 
 export class HostAdbBridgeUnavailableError extends Error {
   constructor(reason) {
@@ -52,6 +62,10 @@ async function adb(args, opts = {}) {
       timeout: opts.timeoutMs || 30_000,
       maxBuffer: 32 * 1024 * 1024,
       encoding: "utf8",
+      origin: "host-adb:command",
+      policy: "allow",
+      scope: "host-adb",
+      shell: false,
     });
     if (stderr && /error:|failed:|protocol fault/i.test(stderr)) {
       throw new HostAdbBridgeUnavailableError(stderr.trim().split("\n")[0]);
@@ -585,6 +599,7 @@ export function createHostAdbBridge(opts = {}) {
 
 // Exposed for unit testing without spawning real adb.
 export const _internals = {
+  adb,
   parseContentQueryRows,
   mergeContactRows,
   listDevices,

package/src/lib/interaction-adapter.js

@@ -179,6 +179,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
 
       this._sendWs({
         ...message,
+        ...(message.type === "question_request" ? { id: requestId } : {}),
         sessionId: this.sessionId,
         requestId,
         // Ride the binding out so the remote UI/bridge can echo it back on the
@@ -238,6 +239,71 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     return answer === "true" || answer === "yes" || answer === "y";
   }
 
+  /**
+   * Agent-core AskUserQuestion transport for Desktop/WebSocket consumers.
+   * It uses the same pending map and `session-answer` resolver as MCP
+   * elicitation, while exposing the stream protocol's `question_request`
+   * shape so capable UIs can render options natively.
+   */
+  async askUser({
+    question,
+    options = null,
+    multiSelect = false,
+    timeoutMs,
+    defaultValue,
+    onTimeout,
+    onReject,
+    turnId,
+    toolUseId,
+    metadata = null,
+  } = {}) {
+    const normalizedTurnId =
+      turnId === undefined || turnId === null ? null : String(turnId);
+    const normalizedToolUseId =
+      toolUseId === undefined || toolUseId === null ? null : String(toolUseId);
+    const questionMetadata = {
+      ...(metadata && typeof metadata === "object" ? metadata : {}),
+      kind: "ask_user_question",
+      ...(normalizedTurnId
+        ? { turnId: normalizedTurnId, turn_id: normalizedTurnId }
+        : {}),
+      ...(normalizedToolUseId
+        ? {
+            toolUseId: normalizedToolUseId,
+            tool_use_id: normalizedToolUseId,
+          }
+        : {}),
+    };
+
+    return this._request(
+      {
+        type: "question_request",
+        questionType: "ask_user_question",
+        question: typeof question === "string" ? question : "",
+        options: Array.isArray(options) ? options : null,
+        multiSelect: multiSelect === true,
+        ...(defaultValue !== undefined ? { defaultValue } : {}),
+        ...(onTimeout ? { onTimeout } : {}),
+        ...(onReject ? { onReject } : {}),
+        ...(Number(timeoutMs) > 0 ? { timeoutMs: Number(timeoutMs) } : {}),
+        ...(normalizedTurnId
+          ? { turnId: normalizedTurnId, turn_id: normalizedTurnId }
+          : {}),
+        ...(normalizedToolUseId
+          ? {
+              toolUseId: normalizedToolUseId,
+              tool_use_id: normalizedToolUseId,
+            }
+          : {}),
+        metadata: questionMetadata,
+      },
+      {
+        kind: "question",
+        ...(Number(timeoutMs) > 0 ? { timeoutMs: Number(timeoutMs) } : {}),
+      },
+    );
+  }
+
   /**
    * Called by ws-server when a session-answer message arrives.
    * Resolves the corresponding pending promise.