chainlesschain 0.162.179 → 0.162.181

package/src/runtime/headless-runner.js

@@ -61,6 +61,11 @@ import { SIDE_EFFECT_LEDGER_EVENT } from "../lib/side-effect-ledger-store.js";
 import { TurnBindingLog, createTurnBindingFeed } from "../lib/turn-binding.js";
 import { TURN_BINDING_EVENT } from "../lib/turn-binding-store.js";
 import { operationIdempotencyKey } from "../lib/idempotency.js";
+import {
+  emitHooksV2Event,
+  executeHooksV2Event,
+  resolvePromptExpansion,
+} from "../lib/hooks-v2-producers.js";
 import { CLISkillLoader } from "../lib/skill-loader.js";
 import { expandFileRefsAsync } from "./file-ref-expander.js";
 import { composeSystemPrompt } from "./system-prompt.js";
@@ -367,6 +372,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   // every existing risk-tier / shell-policy layer runs unchanged.
   let permissionRules = options.permissionRules || null;
   let managedSettings = null;
+  let settingsFiles = [];
   try {
     const { loadSettings, applyManagedPermissionPolicy } =
       await import("../lib/settings-loader.cjs");
@@ -376,6 +382,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
       managedSettingsFile: options.managedSettingsFile,
     });
     managedSettings = loaded.managed;
+    settingsFiles = Array.isArray(loaded.files) ? loaded.files : [];
     if (!permissionRules) {
       const total =
         loaded.rules.allow.length +
@@ -465,6 +472,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
 
   const runLoop = deps.agentLoop || coreAgentLoop;
   const doBootstrap = deps.bootstrap || bootstrap;
+  const executeLifecycleHooks = deps.executeHooksV2Event || executeHooksV2Event;
   const getApprovalGate =
     deps.getApprovalGate ||
     (async () => {
@@ -681,6 +689,48 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     }
   };
 
+  const setupHooks = await executeLifecycleHooks(
+    "Setup",
+    {
+      schema_version: 1,
+      session_id: sessionId,
+      cwd,
+      database_available: db != null,
+      enabled_tools: enabledToolNames,
+      settings_files: settingsFiles,
+    },
+    { failClosed: true },
+  );
+  if (setupHooks.blocked || setupHooks.decision === "block") {
+    const reason =
+      setupHooks.blockingResult?.reason ||
+      setupHooks.error ||
+      "blocked by Setup hook";
+    writeErr(`[hook] ${reason}\n`);
+    emitHeadlessError(reason);
+    return { exitCode: 2, result: reason, isError: true };
+  }
+
+  const expansionHooks = await executeLifecycleHooks(
+    "UserPromptExpansion",
+    {
+      schema_version: 1,
+      session_id: sessionId,
+      cwd,
+      prompt: userContent,
+      original_prompt: prompt,
+    },
+    { failClosed: true },
+  );
+  const expansion = resolvePromptExpansion(userContent, expansionHooks);
+  if (expansion.blocked) {
+    const reason = expansion.reason || "blocked by UserPromptExpansion hook";
+    writeErr(`[hook] ${reason}\n`);
+    emitHeadlessError(reason);
+    return { exitCode: 2, result: reason, isError: true };
+  }
+  userContent = expansion.prompt;
+
   // Load prior conversation when resuming an existing session. The fresh
   // system prompt always leads; we drop any persisted system turns so it is
   // never duplicated.
@@ -1033,8 +1083,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   let _loadedInstructions = null;
   let _loadedPersonaSkills = [];
   let _skillCacheLedger = null;
-  const _runtimeSkillLoader =
-    options.skillLoader || new CLISkillLoader();
+  const _runtimeSkillLoader = options.skillLoader || new CLISkillLoader();
   const systemContent = composeSystemPrompt(
     buildSystemPrompt(cwd, {
       additionalDirectories,
@@ -1967,6 +2016,11 @@ export async function runAgentHeadless(options = {}, deps = {}) {
             // P0-2: settle the in-flight side-effect (commit on success, fail on
             // a clean error) and persist the updated ledger snapshot.
             if (persist && currentSideEffectOpId) {
+              if (event.permission_decision) {
+                sideEffectLedger.annotate(currentSideEffectOpId, {
+                  permissionDecision: event.permission_decision,
+                });
+              }
               if (event.result?._diffReviewAudit) {
                 diffReviewFollowUps.observe(
                   sideEffectLedger,
@@ -1991,6 +2045,12 @@ export async function runAgentHeadless(options = {}, deps = {}) {
               is_error: Boolean(err),
               error: err,
               result: event.result,
+              ...(event.permission_decision_id
+                ? { permission_decision_id: event.permission_decision_id }
+                : {}),
+              ...(event.permission_decision
+                ? { permission_decision: event.permission_decision }
+                : {}),
             });
             if (toolCalls.length > 0) {
               toolCalls[toolCalls.length - 1].is_error = Boolean(err);
@@ -2351,7 +2411,30 @@ export async function runAgentHeadless(options = {}, deps = {}) {
         const { runObserveHooks, dispatchAsyncHooks } =
           await import("../lib/settings-hook-events.js");
         const stopPayload = { reason: endReason, cwd, session_id: sessionId };
-        runObserveHooks(settingsHooks, "Stop", stopPayload, { cwd });
+        const stopOutcome = runObserveHooks(
+          settingsHooks,
+          "Stop",
+          stopPayload,
+          { cwd },
+        );
+        const stopFailures = (stopOutcome?.results || []).filter(
+          (result) =>
+            result?.nonBlockingError === true ||
+            result?.malformedDecision === true ||
+            result?.breakerOpen === true,
+        );
+        if (stopFailures.length > 0) {
+          emitHooksV2Event("StopFailure", {
+            schema_version: 1,
+            session_id: sessionId,
+            phase: "stop-hook",
+            failures: stopFailures.map((failure) => ({
+              command: failure.command || null,
+              exit_code: failure.exitCode ?? null,
+              reason: failure.reason || failure.error || null,
+            })),
+          });
+        }
         // Skip the async Stop dispatch/settle here if the auto-rewake re-drive
         // loop already fired + drained it this run (avoids double-execution).
         if (_hookSupervisor && !_asyncStopHandled) {
@@ -2377,6 +2460,14 @@ export async function runAgentHeadless(options = {}, deps = {}) {
           // re-engage the agent in an interactive session — flag it clearly so a
           // headless caller/CI can react.
           for (const rw of _hookSupervisor.drainRewakes()) {
+            emitHooksV2Event("StopFailure", {
+              schema_version: 1,
+              session_id: sessionId,
+              phase: "async-stop-hook",
+              command: rw.command || null,
+              exit_code: rw.exitCode ?? null,
+              reason: rw.error || "async stop hook requested rewake",
+            });
             writeErr(
               `[async-hook REWAKE] ${rw.command} failed` +
                 `${rw.exitCode != null ? ` (exit ${rw.exitCode})` : ""}` +
@@ -2398,7 +2489,13 @@ export async function runAgentHeadless(options = {}, deps = {}) {
           { reason: "completed", cwd, session_id: sessionId },
           { cwd },
         );
-      } catch {
+      } catch (error) {
+        emitHooksV2Event("StopFailure", {
+          schema_version: 1,
+          session_id: sessionId,
+          phase: "stop-hook-dispatch",
+          reason: error?.message || String(error),
+        });
         // observe-only + best-effort async surfacing
       }
     }

package/src/runtime/headless-stream.js

@@ -21,6 +21,15 @@ import {
   approvalBindingDigest,
   verifyApprovalBinding,
 } from "../lib/agent-authority.js";
+import {
+  normalizeInteractionBinding,
+  sameInteractionBinding,
+} from "../lib/interaction-binding.js";
+import {
+  emitHooksV2Event,
+  executeHooksV2Event,
+  resolvePromptExpansion,
+} from "../lib/hooks-v2-producers.js";
 import { bootstrap } from "./bootstrap.js";
 import { buildSystemPrompt, agentLoop as coreAgentLoop } from "./agent-core.js";
 import { composeSystemPrompt } from "./system-prompt.js";
@@ -183,6 +192,15 @@ export function createStreamCoalescer({
   const gateOn = (field) => !fieldGate || fieldGate[field] !== false;
   const rawEmit = (obj) => {
     let line = obj;
+    if (
+      !gateOn("permission_decision") &&
+      (Object.prototype.hasOwnProperty.call(line, "permission_decision") ||
+        Object.prototype.hasOwnProperty.call(line, "permission_decision_id"))
+    ) {
+      line = { ...line };
+      delete line.permission_decision;
+      delete line.permission_decision_id;
+    }
     if (traceId && gateOn("trace_id")) line = { ...line, trace_id: traceId };
     if (stampSeq && gateOn("seq")) line = { ...line, seq: ++seq };
     writeOut(JSON.stringify(line) + "\n");
@@ -488,6 +506,9 @@ export function parseInputEvent(line) {
       answer: {
         id: String(obj.id),
         value: obj.answer === undefined ? null : obj.answer,
+        ...(obj.binding && typeof obj.binding === "object"
+          ? { binding: normalizeInteractionBinding(obj.binding) }
+          : {}),
       },
     };
   }
@@ -761,8 +782,7 @@ async function runTurn(
         // agent-sdk docs/PROTOCOL.md §1.2.1): the matching tool_result below
         // echoes the same id so UIs can pair calls without adjacency.
         const toolUseId =
-          event.tool_use_id ||
-          (nextToolUseId ? nextToolUseId() : undefined);
+          event.tool_use_id || (nextToolUseId ? nextToolUseId() : undefined);
         const pm = getPlanModeManager();
         const planItem = pm.startPlanItemForTool(event.tool, {
           toolUseId,
@@ -822,6 +842,11 @@ async function runTurn(
         // P0-2: settle the in-flight side-effect (commit on success, fail on
         // a clean error) and persist the updated ledger snapshot.
         if (sideEffects && currentSideEffectOpId) {
+          if (event.permission_decision) {
+            sideEffects.ledger.annotate(currentSideEffectOpId, {
+              permissionDecision: event.permission_decision,
+            });
+          }
           if (event.result?._diffReviewAudit) {
             diffReviewFollowUps.observe(
               sideEffects.ledger,
@@ -866,6 +891,12 @@ async function runTurn(
           is_error: Boolean(err),
           error: err,
           result: event.result,
+          ...(event.permission_decision_id
+            ? { permission_decision_id: event.permission_decision_id }
+            : {}),
+          ...(event.permission_decision
+            ? { permission_decision: event.permission_decision }
+            : {}),
         });
         if (settledItem) {
           emit({ type: "plan_update", ...planSnapshot(pm) });
@@ -1046,6 +1077,7 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
   const input = deps.input || process.stdin;
   const runLoop = deps.agentLoop || coreAgentLoop;
   const doBootstrap = deps.bootstrap || bootstrap;
+  const executeLifecycleHooks = deps.executeHooksV2Event || executeHooksV2Event;
   const doExpand = deps.expandFileRefs || expandFileRefsAsync;
   const runSessionSlashCommand =
     deps.executeSessionSlashCommand || executeSessionSlashCommand;
@@ -1068,7 +1100,12 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
   // client `hello` narrowing the wire features flips these to suppress the
   // additive fields it can't parse. All true by default = current behavior
   // byte-for-byte; the coalescer reads it per line.
-  const fieldGate = { seq: true, trace_id: true, tool_use_id: true };
+  const fieldGate = {
+    seq: true,
+    trace_id: true,
+    tool_use_id: true,
+    permission_decision: true,
+  };
   // Batch consecutive partial-message text/thinking deltas into one stream_event
   // line (Claude-Code 2.1.191 streaming-CPU optimization). `emit` flushes any
   // pending deltas before writing a non-delta line, so ordering is preserved;
@@ -1115,6 +1152,33 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
   const sessionId =
     options.sessionId || `headless-stream-${Date.now()}-${process.pid}`;
 
+  const setupHooks = await executeLifecycleHooks(
+    "Setup",
+    {
+      schema_version: 1,
+      session_id: sessionId,
+      cwd,
+      database_available: db != null,
+      enabled_tools: enabledToolNames,
+      settings_files: settingsFiles,
+    },
+    { failClosed: true },
+  );
+  if (setupHooks.blocked || setupHooks.decision === "block") {
+    const reason =
+      setupHooks.blockingResult?.reason ||
+      setupHooks.error ||
+      "blocked by Setup hook";
+    emit({
+      type: "result",
+      subtype: "blocked",
+      is_error: true,
+      result: reason,
+      session_id: sessionId,
+    });
+    return { exitCode: 2, turns: 0 };
+  }
+
   // Session persistence + resume (chat-panel "session resume" / --resume):
   // an EXPLICIT session id (--session / --resume) opts into JSONL persistence —
   // prior history is rebuilt into the conversation and every new turn is
@@ -1434,17 +1498,29 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
     multiSelect,
     timeoutMs,
     metadata,
+    sessionId: requestedSessionId,
+    turnId,
+    toolUseId,
   } = {}) =>
     new Promise((resolve, reject) => {
       const id = `q-${++questionSeq}`;
+      const binding = normalizeInteractionBinding({
+        sessionId: requestedSessionId ?? sessionId,
+        turnId,
+        toolUseId,
+        sequence: questionSeq,
+      });
       const ms = Number(timeoutMs) > 0 ? Number(timeoutMs) : questionTimeoutMs;
       const timer = setTimeout(() => failQuestion(id, "timeout"), ms);
       timer.unref?.();
-      pendingQuestions.set(id, { resolve, reject, timer });
+      pendingQuestions.set(id, { resolve, reject, timer, binding });
       emit({
         type: "question_request",
         id,
         session_id: sessionId,
+        binding,
+        ...(binding.turnId ? { turn_id: binding.turnId } : {}),
+        ...(binding.toolUseId ? { tool_use_id: binding.toolUseId } : {}),
         question: typeof question === "string" ? question : "",
         options: Array.isArray(qOptions) ? qOptions : null,
         multiSelect: multiSelect === true,
@@ -1491,7 +1567,10 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
   if (options.jsonSchema) {
     try {
       _jso = await import("../lib/json-schema-output.js");
-      _jsonSchema = _jso.loadSchemaFile(_jso._deps.fs, options.jsonSchema);
+      _jsonSchema = await _jso.loadSchemaFileWithRefs(
+        _jso._deps.fs,
+        options.jsonSchema,
+      );
     } catch (err) {
       // Fail-fast, exactly like `cc agent -p --json-schema` on a bad schema.
       writeErr(`Error: ${err.message}\n`);
@@ -1761,32 +1840,91 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
   // handler only after MCP resolution so the client is initialized before use.
   // Reuse the structured Desktop/headless question channel, while preserving
   // the MCP response shape (`action` + object `content`) at this boundary.
+  if (mcp?.mcpClient?.on) {
+    mcp.mcpClient.on("elicitation-deferred", (request) => {
+      emit({
+        type: "elicitation_deferred",
+        session_id: sessionId,
+        server: request.server || null,
+        request_id: request.requestId ?? null,
+        mode: request.mode || "form",
+        message: request.message || "",
+        requested_schema: request.requestedSchema || null,
+        elicitation_id: request.elicitationId || null,
+        url: request.url || null,
+        url_host: request.urlHost || null,
+        reason: request.reason || "no_interactive_host",
+        wire_action: request.wireAction || "decline",
+      });
+    });
+    mcp.mcpClient.on("elicitation-complete", (event) => {
+      emit({
+        type: "elicitation_complete",
+        session_id: sessionId,
+        server: event.server || null,
+        elicitation_id: event.elicitationId || null,
+      });
+    });
+  }
   if (mcp?.mcpClient?.setElicitationHandler && interactiveQuestions) {
     mcp.mcpClient.setElicitationHandler(async (request) => {
-      const { emitHooksV2Event } = await import("../lib/hooks-v2-producers.js");
-      emitHooksV2Event("MCPElicitation", {
+      const hookContext = {
+        schema_version: 1,
         server: request.server || null,
         request_id: request.requestId ?? null,
         message: request.message || "MCP server requests additional input",
         requested_schema: request.requestedSchema || null,
+        mode: request.mode || "form",
+        elicitation_id: request.elicitationId || null,
+        url: request.url || null,
+        url_host: request.urlHost || null,
         session_id: sessionId,
-      });
-      const answer = await interactionAskUser({
-        question: request.message || "MCP server requests additional input",
-        timeoutMs: request.timeoutMs,
-        metadata: {
-          kind: "mcp_elicitation",
-          server: request.server,
-          requestId: request.requestId,
-          requestedSchema: request.requestedSchema || null,
-        },
-      });
-      if (answer == null) return { action: "cancel" };
-      return {
-        action: "accept",
-        content:
-          answer && typeof answer === "object" ? answer : { value: answer },
       };
+      emitHooksV2Event("MCPElicitation", hookContext);
+      emitHooksV2Event("Elicitation", hookContext);
+      try {
+        const answer = await interactionAskUser({
+          question:
+            request.mode === "url"
+              ? `${request.message || "MCP server requests an external interaction"}\nOpen secure URL on ${request.urlHost}?`
+              : request.message || "MCP server requests additional input",
+          timeoutMs: request.timeoutMs,
+          metadata: {
+            kind: "mcp_elicitation",
+            server: request.server,
+            requestId: request.requestId,
+            mode: request.mode || "form",
+            requestedSchema: request.requestedSchema || null,
+            elicitationId: request.elicitationId || null,
+            url: request.url || null,
+            urlHost: request.urlHost || null,
+          },
+        });
+        const response =
+          answer == null
+            ? { action: "cancel" }
+            : request.mode === "url"
+              ? { action: "accept" }
+              : {
+                  action: "accept",
+                  content:
+                    answer && typeof answer === "object"
+                      ? answer
+                      : { value: answer },
+                };
+        emitHooksV2Event("ElicitationResult", {
+          ...hookContext,
+          action: response.action,
+        });
+        return response;
+      } catch (error) {
+        emitHooksV2Event("ElicitationResult", {
+          ...hookContext,
+          action: "cancel",
+          reason: error?.code || error?.message || "interaction_failed",
+        });
+        throw error;
+      }
     });
   }
 
@@ -2044,6 +2182,19 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
         if (parsed.answer) {
           // Answers settle a BLOCKED ask_user_question — never queued. A null
           // value (user cancelled the QuickPick) → user_timeout (model proceeds).
+          const pending = pendingQuestions.get(parsed.answer.id);
+          if (
+            !pending ||
+            !sameInteractionBinding(pending.binding, parsed.answer.binding)
+          ) {
+            emit({
+              type: "question_response_rejected",
+              id: parsed.answer.id,
+              reason: "binding_mismatch",
+              session_id: sessionId,
+            });
+            continue;
+          }
           if (parsed.answer.value == null)
             failQuestion(parsed.answer.id, "cancelled");
           else
@@ -2196,6 +2347,15 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
         messages_before: before,
         messages_after: messages.length,
       });
+      emitHooksV2Event("PostCompact", {
+        schema_version: 1,
+        trigger: "manual",
+        session_id: sessionId,
+        messages_before: before,
+        messages_after: messages.length,
+        stats,
+        cwd,
+      });
       continue;
     }
 
@@ -2439,6 +2599,32 @@ export async function runAgentHeadlessStream(options = {}, deps = {}) {
       for (const w of expanded.warnings) writeErr(`  @ref: ${w}\n`);
     }
 
+    const expansionHooks = await executeLifecycleHooks(
+      "UserPromptExpansion",
+      {
+        schema_version: 1,
+        session_id: sessionId,
+        turn: turns + 1,
+        cwd,
+        prompt: userContent,
+        original_prompt: parsed.text,
+      },
+      { failClosed: true },
+    );
+    const expansion = resolvePromptExpansion(userContent, expansionHooks);
+    if (expansion.blocked) {
+      emit({
+        type: "result",
+        subtype: "blocked",
+        is_error: true,
+        result: expansion.reason || "blocked by UserPromptExpansion hook",
+        session_id: sessionId,
+      });
+      sawError = true;
+      continue;
+    }
+    userContent = expansion.prompt;
+
     // settings.json UserPromptSubmit hooks. block → skip this turn; context → inject.
     if (settingsHooks) {
       try {

package/src/runtime/mcp-config.js

@@ -647,6 +647,12 @@ export async function loadProjectMcp(opts = {}, deps = {}) {
   const trust =
     deps.projectMcpTrust ||
     (await import("../lib/project-mcp-trust.js").catch(() => null));
+  if (!trust) {
+    writeErr(
+      "  mcp: SKIPPING project .mcp.json — project trust service is unavailable.\n",
+    );
+    return deps.into || null;
+  }
 
   const servers = {};
   const seenFiles = [];
@@ -661,26 +667,32 @@ export async function loadProjectMcp(opts = {}, deps = {}) {
       writeErr(`  mcp: ignoring malformed ${file} (${err.message})\n`);
       continue;
     }
-    if (trust) {
-      try {
-        const check = trust.checkProjectMcpTrust(file, content);
-        if (check.status === "changed") {
-          if (trust.projectMcpRetrustRequested(env)) {
-            trust.recordProjectMcpTrust(file, content);
-            writeErr(`  mcp: ${file} re-trusted (CC_PROJECT_MCP_TRUST).\n`);
-          } else {
-            writeErr(
-              `  mcp: SKIPPING ${file} — its content changed since it was last trusted. ` +
-                `Review the diff, then re-trust with CC_PROJECT_MCP_TRUST=1 or \`cc mcp trust-project\`.\n`,
-            );
-            continue;
+    try {
+      const check = trust.checkProjectMcpTrust(file, content);
+      if (check.status === "changed") {
+        if (trust.projectMcpRetrustRequested(env)) {
+          if (trust.recordProjectMcpTrust(file, content) !== true) {
+            throw new Error("project MCP trust record was not persisted");
           }
-        } else if (check.status === "first-use") {
-          trust.recordProjectMcpTrust(file, content);
+          writeErr(`  mcp: ${file} re-trusted (CC_PROJECT_MCP_TRUST).\n`);
+        } else {
+          writeErr(
+            `  mcp: SKIPPING ${file} — its content changed since it was last trusted. ` +
+              `Review the diff, then re-trust with CC_PROJECT_MCP_TRUST=1 or \`cc mcp trust-project\`.\n`,
+          );
+          continue;
+        }
+      } else if (check.status === "first-use") {
+        if (trust.recordProjectMcpTrust(file, content) !== true) {
+          throw new Error("project MCP trust record was not persisted");
         }
-      } catch {
-        /* trust bookkeeping is best-effort; the opt-in gate above still holds */
       }
+    } catch (err) {
+      writeErr(
+        `  mcp: SKIPPING ${file} — project trust state is unavailable ` +
+          `(${err?.message || "unknown error"}).\n`,
+      );
+      continue;
     }
     const parsed = parseMcpServers(raw);
     if (Object.keys(parsed).length > 0) {

package/src/runtime/policies/agent-policy.js

@@ -33,6 +33,8 @@ export function resolveAgentPolicy({
       : [],
     sandbox: overrides.sandbox || null,
     autoCheckpoint: overrides.autoCheckpoint === true,
+    worktreeId:
+      overrides.worktreeId == null ? null : String(overrides.worktreeId),
     systemPrompt: overrides.systemPrompt || null,
     appendSystemPrompt: overrides.appendSystemPrompt || null,
     fallbackModel: overrides.fallbackModel || null,