chainlesschain 0.162.176 → 0.162.178

package/src/runtime/agent-core.js

@@ -16,15 +16,14 @@
 
 import fs from "fs";
 import path from "path";
-import { execSync, spawn, spawnSync } from "child_process";
 import broker from "../lib/process-execution-broker/index.js";
 import os from "os";
 import sharedCodingAgentPolicy from "./coding-agent-policy.cjs";
 import sharedShellPolicy from "./coding-agent-shell-policy.cjs";
 import sharedPermissionRules from "../lib/permission-rules.cjs";
 import sharedSettingsHooks from "../lib/settings-hooks.cjs";
-import sharedHookRunner from "../lib/hook-runner.cjs";
-import sharedHookEvents from "../lib/settings-hook-events.cjs";
+import sharedHookRunner from "../lib/hook-runner.js";
+import sharedHookEvents from "../lib/settings-hook-events.js";
 import { mergeProviderOptions } from "../lib/provider-options.js";
 import { applyCredentialProxy } from "../lib/credential-proxy.js";
 import { describeBackgroundCommand } from "../lib/terminal-context.js";
@@ -60,6 +59,7 @@ import {
 } from "../lib/idempotency.js";
 import { buildSearchCommand } from "../lib/search-command.js";
 import { discoverCommands } from "../lib/slash-commands.js";
+import { createSkillProcessBroker } from "../lib/skill-process-broker.js";
 import {
   isRetryableStreamError,
   STREAM_RETRY_BASE_MS,
@@ -80,12 +80,21 @@ import {
   imageUrlBlockToAnthropic,
 } from "../lib/image-input.js";
 import { executeToolSearch, gateDeferredMcpCall } from "./mcp-tool-search.js";
-import { emitHooksV2Event } from "../lib/hooks-v2-producers.js";
+import {
+  emitHooksV2Event,
+  executeHooksV2Event,
+} from "../lib/hooks-v2-producers.js";
 import {
   admitTool,
   buildToolAttribution,
 } from "../lib/agent-tool-admission.js";
 import { evaluateUnattendedShellAction } from "../lib/unattended-action-policy.js";
+import {
+  formatProviderHttpError,
+  formatProviderResponseError,
+} from "../lib/provider-http-error.js";
+
+export { formatProviderHttpError };
 
 /**
  * Names of MCP servers currently mounted by an in-flight run_skill call.
@@ -113,6 +122,33 @@ const {
   withDeliveryId,
 } = sharedHookEvents;
 
+const searchProcessRunner = broker.execSync.bind(broker);
+const runCodeProcessRunner = broker.execFileSync.bind(broker);
+
+export const _agentToolProcessDeps = {
+  runSearch: searchProcessRunner,
+  runCode: runCodeProcessRunner,
+};
+
+function runSearchProcess(command, options = {}) {
+  return _agentToolProcessDeps.runSearch(command, {
+    ...options,
+    origin: "agent-core:search-files",
+    policy: "allow",
+    scope: "agent-core",
+  });
+}
+
+function runCodeProcess(file, args, options = {}, origin = "run-code") {
+  return _agentToolProcessDeps.runCode(file, args, {
+    ...options,
+    origin: `agent-core:${origin}`,
+    policy: "allow",
+    scope: "agent-core",
+    shell: false,
+  });
+}
+
 // ─── Background shell tasks ────────────────────────────────────────────────
 //
 // run_shell is synchronous (execSync) and capped at a foreground timeout, which
@@ -231,25 +267,54 @@ function _releaseBgChildHandles(task) {
   }
 }
 
+const backgroundTaskRunner = broker.spawn.bind(broker);
+const backgroundTaskSyncRunner = broker.spawnSync.bind(broker);
+
+export const _backgroundProcessDeps = {
+  run: backgroundTaskRunner,
+  runSync: backgroundTaskSyncRunner,
+};
+
+export function _runBackgroundTaskkill(pid, { sync = false } = {}) {
+  const args = ["/pid", String(pid), "/T", "/F"];
+  const options = {
+    windowsHide: true,
+    origin: "agent-core:background-taskkill",
+    policy: "allow",
+    scope: "agent-core",
+  };
+  return sync
+    ? _backgroundProcessDeps.runSync("taskkill", args, options)
+    : _backgroundProcessDeps.run("taskkill", args, options);
+}
+
+const gitProcessRunner = broker.spawnSync.bind(broker);
+
+export const _gitProcessDeps = {
+  run: gitProcessRunner,
+};
+
 function _killTask(task) {
   const child = task?.child;
   if (!child || child.killed || task?.status !== "running") return false;
   try {
     if (process.platform === "win32") {
       if (child.pid) {
-        const tk = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
-          windowsHide: true,
-        });
-        // A spawn that fails to launch emits an async 'error' event — with no
-        // listener Node rethrows it as an UNCAUGHT exception (the try/catch
-        // here can't catch the async emit), crashing the CLI. Handle it and
-        // fall back to a direct kill.
-        tk.on("error", () => {
+        const tk = _runBackgroundTaskkill(child.pid);
+        const fallbackDirectKill = () => {
           try {
-            child.kill();
+            if (!child.killed) child.kill("SIGKILL");
           } catch {
             /* already dead */
           }
+        };
+        // A launch failure emits 'error'; a permissions/policy failure instead
+        // launches taskkill successfully and exits non-zero. Both must fall
+        // back or the background command remains alive while teardown reports
+        // success.
+        tk.once("error", fallbackDirectKill);
+        tk.once("close", (code) => {
+          if (code !== 0) fallbackDirectKill();
         });
       } else {
         child.kill();
@@ -310,9 +375,13 @@ function _killTaskSync(task) {
   try {
     if (process.platform === "win32") {
       if (child.pid) {
-        spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
-          windowsHide: true,
-        });
+        const killed = _runBackgroundTaskkill(child.pid, { sync: true });
+        if (killed.error || killed.status !== 0) {
+          // Restricted runners can execute taskkill but receive a non-zero
+          // access/policy result. Direct termination is the synchronous
+          // last-resort for the child handle we own.
+          child.kill("SIGKILL");
+        }
       } else {
         child.kill();
       }
@@ -601,6 +670,33 @@ async function requestInteractivePermission(
   cwd,
   confirmArgs,
 ) {
+  const hooksV2 = await executeHooksV2Event(
+    "PermissionRequest",
+    {
+      schema_version: 1,
+      session_id: context.sessionId || null,
+      turn_id: context.turnId || null,
+      tool_use_id: context.toolCallId || null,
+      tool_name: name,
+      input_keys:
+        args && typeof args === "object" ? Object.keys(args).sort() : [],
+      reason: confirmArgs?.reason || null,
+      cwd,
+    },
+    { failClosed: true },
+  );
+  if (hooksV2.decision === "allow") return true;
+  if (hooksV2.blocked || hooksV2.decision === "block") {
+    emitHooksV2Event("PermissionDenied", {
+      schema_version: 1,
+      session_id: context.sessionId || null,
+      turn_id: context.turnId || null,
+      tool_use_id: context.toolCallId || null,
+      tool_name: name,
+      source: "hooks-v2",
+    });
+    return false;
+  }
   const verdict = runSettingsPermissionRequestHooks(
     name,
     args,
@@ -609,9 +705,31 @@ async function requestInteractivePermission(
     confirmArgs?.reason,
   );
   if (verdict.decision === "allow") return true;
-  if (verdict.decision === "deny") return false;
+  if (verdict.decision === "deny") {
+    emitHooksV2Event("PermissionDenied", {
+      schema_version: 1,
+      session_id: context.sessionId || null,
+      turn_id: context.turnId || null,
+      tool_use_id: context.toolCallId || null,
+      tool_name: name,
+      source: "settings-hook",
+    });
+    return false;
+  }
   const confirm = context.permissionConfirm || context.shellConfirm || null;
-  return typeof confirm === "function" ? await confirm(confirmArgs) : false;
+  const approved =
+    typeof confirm === "function" ? await confirm(confirmArgs) : false;
+  if (!approved) {
+    emitHooksV2Event("PermissionDenied", {
+      schema_version: 1,
+      session_id: context.sessionId || null,
+      turn_id: context.turnId || null,
+      tool_use_id: context.toolCallId || null,
+      tool_name: name,
+      source: typeof confirm === "function" ? "user" : "no-confirmer",
+    });
+  }
+  return approved;
 }
 
 // ─── Tool definitions ────────────────────────────────────────────────────
@@ -693,6 +811,21 @@ export function reloadSkills() {
 let _cachedPython = null;
 let _cachedEnvInfo = null;
 
+const environmentProbeRunner = broker.execFileSync.bind(broker);
+
+export const _environmentProcessDeps = {
+  run: environmentProbeRunner,
+};
+
+function runEnvironmentProbe(file, args, options = {}) {
+  return _environmentProcessDeps.run(file, args, {
+    ...options,
+    origin: "agent-core:environment-probe",
+    policy: "allow",
+    scope: "agent-core",
+  });
+}
+
 /**
  * Get cached Python interpreter info (reuses cli-anything-bridge detection).
  * @returns {{ found: boolean, command?: string, version?: string }}
@@ -716,7 +849,7 @@ export function getEnvironmentInfo() {
   let pipAvailable = false;
   if (py.found) {
     try {
-      execSync(`${py.command} -m pip --version`, {
+      runEnvironmentProbe(py.command, ["-m", "pip", "--version"], {
         encoding: "utf-8",
         timeout: 10000,
         stdio: ["pipe", "pipe", "pipe"],
@@ -729,7 +862,7 @@ export function getEnvironmentInfo() {
 
   let nodeVersion = null;
   try {
-    nodeVersion = execSync("node --version", {
+    nodeVersion = runEnvironmentProbe(process.execPath, ["--version"], {
       encoding: "utf-8",
       timeout: 5000,
     }).trim();
@@ -739,7 +872,7 @@ export function getEnvironmentInfo() {
 
   let gitAvailable = false;
   try {
-    execSync("git --version", {
+    runEnvironmentProbe("git", ["--version"], {
       encoding: "utf-8",
       timeout: 5000,
       stdio: ["pipe", "pipe", "pipe"],
@@ -932,13 +1065,14 @@ export function buildSystemPrompt(cwd, opts = {}) {
 
   // Append auto-activated persona skills
   try {
-    const loader = new CLISkillLoader();
-    const allSkills = loader.getResolvedSkills();
-    const personaSkills = allSkills.filter(
-      (s) => s.category === "persona" && s.activation === "auto",
-    );
+    const loader = opts.skillLoader || new CLISkillLoader();
+    const personaSkills = loader.getAutoActivatedPersonas({
+      sessionId: opts.sessionId,
+      turnId: opts.turnId,
+      loadedBecause: "persona_auto",
+    });
     if (typeof opts.onSkillsLoaded === "function") {
-      opts.onSkillsLoaded(personaSkills);
+      opts.onSkillsLoaded(personaSkills, loader.getCacheLedger());
     }
     for (const p of personaSkills) {
       if (p.body?.trim()) {
@@ -1387,11 +1521,11 @@ export async function executeTool(name, args, context = {}) {
         override.capabilityGranted ?? admission.capabilityGranted,
       policyAllowed:
         override.policyAllowed ??
-        (context.hostManagedToolPolicy ?
-          ((context.hostManagedToolPolicy?.tools ||
-            context.hostManagedToolPolicy?.toolPolicies || {})[name]
-            ?.allowed !== false) :
-          admission.policyAllowed),
+        (context.hostManagedToolPolicy
+          ? (context.hostManagedToolPolicy?.tools ||
+              context.hostManagedToolPolicy?.toolPolicies ||
+              {})[name]?.allowed !== false
+          : admission.policyAllowed),
       permissionGranted:
         override.permissionGranted ?? admission.permissionGranted,
       budgetOk: override.budgetOk ?? admission.budgetOk,
@@ -1736,6 +1870,52 @@ export async function executeTool(name, args, context = {}) {
   // capable: a `block` (exit 2 / {decision:block}) stops the tool here, an
   // `ask` routes to the confirmer. Runs after permission resolution so a
   // settings deny / host deny short-circuits before any hook process spawns.
+  const hooksV2Pre = await executeHooksV2Event(
+    "PreToolUse",
+    {
+      schema_version: 1,
+      session_id: context.sessionId || null,
+      turn_id: context.turnId || null,
+      tool_use_id: context.toolCallId || null,
+      tool_name: name,
+      input_keys:
+        args && typeof args === "object" ? Object.keys(args).sort() : [],
+      cwd,
+    },
+    { failClosed: true },
+  );
+  if (hooksV2Pre.blocked || hooksV2Pre.decision === "block") {
+    return {
+      error: `[Hook v2] PreToolUse blocked "${name}".`,
+      policy: { decision: "block", via: "hooks-v2" },
+    };
+  }
+  if (hooksV2Pre.requiresApproval || hooksV2Pre.decision === "ask") {
+    const confirm = context.permissionConfirm || context.shellConfirm || null;
+    const approved =
+      typeof confirm === "function"
+        ? await confirm({
+            tool: name,
+            args,
+            reason: "Hooks v2 PreToolUse requested confirmation",
+            source: "hooks-v2",
+          })
+        : false;
+    if (!approved) {
+      emitHooksV2Event("PermissionDenied", {
+        schema_version: 1,
+        session_id: context.sessionId || null,
+        turn_id: context.turnId || null,
+        tool_use_id: context.toolCallId || null,
+        tool_name: name,
+        source: "hooks-v2",
+      });
+      return {
+        error: `[Hook v2] PreToolUse confirmation denied for "${name}".`,
+        policy: { decision: "deny", via: "hooks-v2" },
+      };
+    }
+  }
   if (hookDb) {
     try {
       await executeHooks(hookDb, HookEvents.PreToolUse, {
@@ -1775,6 +1955,8 @@ export async function executeTool(name, args, context = {}) {
       parentMessages: context.parentMessages,
       interaction: context.interaction,
       sessionId: context.sessionId || null,
+      turnId: context.turnId || null,
+      toolCallId: context.toolCallId || null,
       // Parent LLM config — documented at toolContext as forwarded to
       // spawn_sub_agent for provider/key inheritance; without this line it
       // never actually reached executeToolInner (sub-agents silently fell
@@ -2586,6 +2768,8 @@ async function executeToolInner(
     parentMessages,
     interaction,
     sessionId,
+    turnId,
+    toolCallId,
     hostManagedToolPolicy,
     externalToolDescriptors,
     externalToolExecutors,
@@ -3158,9 +3342,8 @@ async function executeToolInner(
       // from an ambient system command in the process audit log.
       let pluginBinProvenance = null;
       try {
-        const { resolvePluginBinCommand } = await import(
-          "../lib/plugin-runtime/bin.js"
-        );
+        const { resolvePluginBinCommand } =
+          await import("../lib/plugin-runtime/bin.js");
         pluginBinProvenance = resolvePluginBinCommand(args.command, { cwd });
       } catch {
         pluginBinProvenance = null;
@@ -3551,12 +3734,15 @@ async function executeToolInner(
       // command-execution bypass for a prompt-injected agent. Quoted args (a
       // commit message) keep their content via the quote-aware tokenizer.
       const gitArgs = tokenizeShellWords(normalizedCommand);
-      const res = spawnSync("git", gitArgs, {
+      const res = _gitProcessDeps.run("git", gitArgs, {
         cwd: args.cwd || cwd,
         encoding: "utf8",
         timeout: 60000,
         maxBuffer: 1024 * 1024,
         windowsHide: true,
+        origin: "agent-core:git-command",
+        policy: "allow",
+        scope: "agent-core",
       });
       const readOnly = isReadOnlyGitCommand(normalizedCommand);
       if (res.error) {
@@ -3807,16 +3993,62 @@ async function executeToolInner(
           multiSelect: args.multiSelect === true,
           timeoutMs:
             typeof args.timeoutMs === "number" ? args.timeoutMs : 60000,
+          defaultValue: args.defaultValue,
+          onTimeout: args.onTimeout || "error",
+          onReject: args.onReject || "error",
           sessionId,
+          turnId,
+          toolUseId: toolCallId,
         });
         return attachDescriptor({ answer });
       } catch (err) {
-        if (err && err.code === "USER_TIMEOUT") {
+        const failureKind =
+          err?.code === "USER_TIMEOUT"
+            ? "timeout"
+            : [
+                  "USER_REJECTED",
+                  "INTERACTION_REJECTED",
+                  "INTERACTION_CANCELLED",
+                ].includes(err?.code)
+              ? "reject"
+              : null;
+        const strategy =
+          failureKind === "timeout"
+            ? args.onTimeout || "error"
+            : failureKind === "reject"
+              ? args.onReject || "error"
+              : "error";
+        if (failureKind && strategy === "useDefault") {
+          if (!Object.prototype.hasOwnProperty.call(args, "defaultValue")) {
+            return attachDescriptor({
+              error: `${failureKind === "timeout" ? "user_timeout" : "user_rejected"}: useDefault requires defaultValue`,
+            });
+          }
+          return attachDescriptor({
+            answer: args.defaultValue,
+            fallback: "default",
+            reason: failureKind,
+          });
+        }
+        if (failureKind && strategy === "skip") {
+          return attachDescriptor({
+            answer: null,
+            skipped: true,
+            reason: failureKind,
+          });
+        }
+        if (failureKind === "timeout") {
           return attachDescriptor({
             error: "user_timeout",
             hint: "User did not respond in time. Proceed with best judgement.",
           });
         }
+        if (failureKind === "reject") {
+          return attachDescriptor({
+            error: "user_rejected",
+            hint: "The user declined this question. Do not assume consent.",
+          });
+        }
         return attachDescriptor({
           error: `ask_user_question failed: ${err.message}`,
         });
@@ -4157,7 +4389,7 @@ async function executeToolInner(
         };
         try {
           if (!fs.existsSync(root)) continue;
-          const output = execSync(cmd, {
+          const output = runSearchProcess(cmd, {
             cwd: root,
             encoding: "utf8",
             timeout: 10000,
@@ -4345,7 +4577,7 @@ async function executeToolInner(
             : "No skills found. Make sure you're in the ChainlessChain project root or have skills installed.",
         });
       }
-      const match = allSkills.find(
+      let match = allSkills.find(
         (s) => s.id === args.skill_name || s.dirName === args.skill_name,
       );
       if (!match || !match.hasHandler) {
@@ -4353,6 +4585,20 @@ async function executeToolInner(
           error: `Skill "${args.skill_name}" not found or has no handler. Use list_skills to see available skills.`,
         });
       }
+      try {
+        if (typeof skillLoader.materializeSkill === "function") {
+          match = skillLoader.materializeSkill(match, {
+            sessionId,
+            turnId,
+            loadedBecause: "run_skill",
+            bodyIncluded: false,
+          });
+        }
+      } catch (error) {
+        return attachDescriptor({
+          error: `Skill "${args.skill_name}" body could not be loaded: ${error.message}`,
+        });
+      }
 
       // Check if skill requests isolation (via SKILL.md frontmatter)
       const skillIsolation = match.isolation === true;
@@ -4428,7 +4674,7 @@ async function executeToolInner(
             onWarn: (msg) => {
               // Non-fatal — logged as warning, skipped servers captured
               // in mountResult.skipped.
-              // eslint-disable-next-line no-console
+
               console.warn(msg);
             },
           });
@@ -4458,6 +4704,7 @@ async function executeToolInner(
         const taskContext = {
           projectRoot: cwd,
           workspacePath: cwd,
+          processBroker: createSkillProcessBroker(match),
           // Expose the MCP client + mounted servers so the skill handler
           // can call MCP tools directly without going through the agent
           // loop. Handlers that don't need MCP can ignore these.
@@ -4510,6 +4757,11 @@ async function executeToolInner(
             s.category.toLowerCase().includes(q),
         );
       }
+      skillLoader.recordDescriptorUse?.(skills, {
+        sessionId,
+        turnId,
+        loadedBecause: "list_skills",
+      });
       return attachDescriptor({
         count: skills.length,
         skills: skills.map((s) => ({
@@ -4763,7 +5015,7 @@ async function _executeRunCode(args, cwd) {
     const start = Date.now();
     let output;
     try {
-      output = execSync(`${interpreter} "${scriptPath}"`, {
+      output = runCodeProcess(interpreter, [scriptPath], {
         cwd,
         encoding: "utf8",
         timeout: timeoutSec * 1000,
@@ -4863,12 +5115,18 @@ async function _executeRunCode(args, cwd) {
 
           // Attempt pip install
           try {
-            execSync(`${interpreter} -m pip install ${packageName}`, {
-              encoding: "utf-8",
-              timeout: 120000,
-              maxBuffer: 2 * 1024 * 1024,
-              stdio: ["pipe", "pipe", "pipe"],
-            });
+            runCodeProcess(
+              interpreter,
+              ["-m", "pip", "install", packageName],
+              {
+                cwd,
+                encoding: "utf-8",
+                timeout: 120000,
+                maxBuffer: 2 * 1024 * 1024,
+                stdio: ["pipe", "pipe", "pipe"],
+              },
+              "run-code-install",
+            );
             recordInstallAudit({
               package: packageName,
               interpreter,
@@ -4879,12 +5137,17 @@ async function _executeRunCode(args, cwd) {
 
             // Retry execution
             const retryStart = Date.now();
-            const retryOutput = execSync(`${interpreter} "${scriptPath}"`, {
-              cwd,
-              encoding: "utf8",
-              timeout: timeoutSec * 1000,
-              maxBuffer: 5 * 1024 * 1024,
-            });
+            const retryOutput = runCodeProcess(
+              interpreter,
+              [scriptPath],
+              {
+                cwd,
+                encoding: "utf8",
+                timeout: timeoutSec * 1000,
+                maxBuffer: 5 * 1024 * 1024,
+              },
+              "run-code-retry",
+            );
             const retryDuration = Date.now() - retryStart;
 
             return {
@@ -5034,6 +5297,55 @@ export function safeStringifyToolResult(value) {
   }
 }
 
+function emitToolHookLifecycle({
+  tool,
+  args,
+  result,
+  error = null,
+  sessionId = null,
+  turnId = null,
+  toolUseId = null,
+  cwd = process.cwd(),
+}) {
+  const failed = Boolean(error || result?.error);
+  const base = {
+    schema_version: 1,
+    session_id: sessionId,
+    turn_id: turnId,
+    tool_use_id: toolUseId,
+    tool_name: tool,
+    duration_ms: Number(result?.toolTelemetryRecord?.durationMs || 0),
+    cwd,
+  };
+  emitHooksV2Event(failed ? "PostToolUseFailure" : "PostToolUse", {
+    ...base,
+    ...(failed
+      ? {
+          error_code:
+            result?.error?.code ||
+            result?.code ||
+            (typeof error === "object" ? error?.code : null) ||
+            "tool_error",
+        }
+      : {}),
+  });
+  if (!failed && GUARDED_FILE_MUTATION_TOOLS.has(tool)) {
+    const changedPath =
+      args?.path ||
+      args?.filePath ||
+      args?.file_path ||
+      args?.targetPath ||
+      args?.target_path ||
+      null;
+    emitHooksV2Event("FileChanged", {
+      ...base,
+      path: changedPath == null ? null : String(changedPath),
+      operation: tool,
+    });
+  }
+  return failed;
+}
+
 /**
  * Execute a spawn_sub_agent tool call.
  * Creates an isolated SubAgentContext, runs it, and returns only the summary.
@@ -5618,10 +5930,7 @@ async function _executeSpawnSubAgent(args, ctx) {
         task: subCtx.task,
         background: payload?.background === true,
       });
-    } else if (
-      type === "sub-agent.completed" ||
-      type === "sub-agent.failed"
-    ) {
+    } else if (type === "sub-agent.completed" || type === "sub-agent.failed") {
       emitHooksV2Event("TaskCompleted", {
         task_id: subCtx.id,
         session_id: parentSessionId,
@@ -5700,6 +6009,8 @@ async function _executeSpawnSubAgent(args, ctx) {
       outcome: null,
       hookFeedback: null,
       promise: null,
+      recoveryBinding: () =>
+        subCtx.recoveryBinding(entry.outcome?.result || null),
     };
     // Settle-capture wrapper: the stored promise NEVER rejects, so an
     // unconsumed handle can't surface as an unhandled rejection.
@@ -5746,6 +6057,7 @@ async function _executeSpawnSubAgent(args, ctx) {
       subAgentId: subCtx.id,
       role: subCtx.role,
       parentSessionId,
+      childBinding: subCtx.recoveryBinding(),
       note: "Sub-agent is running in the background. Its result will be delivered to you automatically in a later turn — continue with other work; the run will not finish before the result arrives.",
     };
   }
@@ -5793,6 +6105,7 @@ async function _executeSpawnSubAgent(args, ctx) {
       subAgentId: subCtx.id,
       role: subCtx.role,
       parentSessionId,
+      childBinding: subCtx.recoveryBinding(result),
       summary: result.summary,
       toolsUsed: result.toolsUsed,
       iterationCount: result.iterationCount,
@@ -5824,6 +6137,7 @@ async function _executeSpawnSubAgent(args, ctx) {
       subAgentId: subCtx.id,
       role: subCtx.role,
       parentSessionId,
+      childBinding: subCtx.recoveryBinding(subCtx.result),
     };
   }
 }
@@ -5914,7 +6228,7 @@ export async function chatWithTools(rawMessages, options) {
       }),
     });
     if (!response.ok) {
-      throw new Error(formatProviderHttpError("ollama", response.status));
+      throw new Error(await formatProviderResponseError("ollama", response));
     }
     const data = await response.json();
     if (data.prompt_eval_count || data.eval_count) {
@@ -6041,7 +6355,7 @@ export async function chatWithTools(rawMessages, options) {
     });
 
     if (!response.ok) {
-      throw new Error(formatProviderHttpError("anthropic", response.status));
+      throw new Error(await formatProviderResponseError("anthropic", response));
     }
 
     const data = await response.json();
@@ -6148,7 +6462,7 @@ export async function chatWithTools(rawMessages, options) {
   });
 
   if (!response.ok) {
-    throw new Error(formatProviderHttpError(provider, response.status));
+    throw new Error(await formatProviderResponseError(provider, response));
   }
 
   const data = await response.json();
@@ -6271,23 +6585,9 @@ export function _streamErrorDisposition(err, signal, partialText) {
  * means a missing/invalid API key for the ACTIVE provider — and because the
  * provider is resolved from config, a surprise "anthropic 401" usually means
  * the effective provider differs from what the user configured. Name the
- * provider and point at the fix instead of dumping a bare status code. Pure +
- * exported for tests.
+ * provider and point at the appropriate key, billing, or permission fix
+ * instead of dumping a bare status code. Pure + exported for tests.
  */
-export function formatProviderHttpError(provider, status) {
-  const base = `${provider} API error: HTTP ${status}`;
-  if (status === 401 || status === 403) {
-    return (
-      `${base} — authentication failed: the API key for provider "${provider}" ` +
-      `is missing or invalid. Check "cc config get llm.provider" and ` +
-      `"cc config get llm.apiKey" (or run Configure LLM). A surprise "${provider}" ` +
-      `here usually means the effective provider differs from the one you configured.`
-    );
-  }
-  if (status === 429) return `${base} — rate limited; please retry shortly.`;
-  return base;
-}
-
 /**
  * Is this error from a streaming chat request a transient API CONNECTION drop
  * that is safe to retry? True only for genuine network failures (reset /
@@ -6481,7 +6781,7 @@ async function _chatOllamaStreaming(
     body: JSON.stringify({ ...body, stream: true }),
   });
   if (!response.ok) {
-    throw new Error(formatProviderHttpError("ollama", response.status));
+    throw new Error(await formatProviderResponseError("ollama", response));
   }
   const state = _ollamaInitState();
   const reader = response.body.getReader();
@@ -6667,7 +6967,7 @@ async function _chatAnthropicStreaming(
     body: JSON.stringify(body),
   });
   if (!response.ok) {
-    throw new Error(formatProviderHttpError("anthropic", response.status));
+    throw new Error(await formatProviderResponseError("anthropic", response));
   }
   const state = _anthropicInitState();
   const reader = response.body.getReader();
@@ -6819,7 +7119,7 @@ async function _chatOpenAIStreaming(
     body: JSON.stringify(body),
   });
   if (!response.ok) {
-    throw new Error(formatProviderHttpError(provider, response.status));
+    throw new Error(await formatProviderResponseError(provider, response));
   }
   const state = _openaiInitState();
   const reader = response.body.getReader();
@@ -7249,6 +7549,10 @@ export async function* agentLoop(messages, options) {
     cwd: options.cwd || process.cwd(),
     planManager: options.planManager || null,
     sessionId: options.sessionId || null,
+    // One agentLoop invocation represents one user turn even when it performs
+    // several model/tool iterations. Hosts may supply their persisted turn id;
+    // otherwise the run id is the stable in-process binding.
+    turnId: options.turnId || runId,
     hostManagedToolPolicy: options.hostManagedToolPolicy || null,
     externalToolDescriptors: options.externalToolDescriptors || null,
     externalToolExecutors: options.externalToolExecutors || null,
@@ -7678,6 +7982,7 @@ export async function* agentLoop(messages, options) {
           role: entry.role,
           error: entry.outcome?.error || null,
           summary: entry.outcome?.result?.summary || null,
+          childBinding: entry.recoveryBinding?.() || null,
         };
       }
     }
@@ -7821,6 +8126,7 @@ export async function* agentLoop(messages, options) {
             role: entry.role,
             error: entry.outcome?.error || null,
             summary: entry.outcome?.result?.summary || null,
+            childBinding: entry.recoveryBinding?.() || null,
           };
         }
         continue;
@@ -7944,9 +8250,9 @@ export async function* agentLoop(messages, options) {
         let toolArgs;
         try {
           toolArgs =
-          typeof call.function.arguments === "string"
-            ? JSON.parse(call.function.arguments)
-            : call.function.arguments;
+            typeof call.function.arguments === "string"
+              ? JSON.parse(call.function.arguments)
+              : call.function.arguments;
         } catch {
           toolArgs = {};
         }
@@ -7966,6 +8272,8 @@ export async function* agentLoop(messages, options) {
           type: "tool-executing",
           tool: call.function.name,
           args: toolArgs,
+          tool_use_id: call.id,
+          turn_id: `${runId}:t${budget.consumed}`,
         };
         const { result: toolResult, error: toolError } = await promise;
         throwIfAborted(signal);
@@ -7981,6 +8289,12 @@ export async function* agentLoop(messages, options) {
           tool: call.function.name,
           result: toolResult,
           error: toolError,
+          tool_use_id: call.id,
+          turn_id: `${runId}:t${budget.consumed}`,
+          permission_decision_id: permissionDecisionId(
+            call.id,
+            toolResult?.policy,
+          ),
         };
         messages.push({
           role: "tool",
@@ -8009,6 +8323,8 @@ export async function* agentLoop(messages, options) {
           tool: "(unknown)",
           result: { error: reason },
           error: reason,
+          tool_use_id: call?.id || null,
+          turn_id: `${runId}:t${budget.consumed}`,
         };
         messages.push({
           role: "tool",
@@ -8035,9 +8351,22 @@ export async function* agentLoop(messages, options) {
         toolName,
         toolArgs,
       );
-      if (cpId) yield { type: "checkpoint", id: cpId, tool: toolName };
+      if (cpId)
+        yield {
+          type: "checkpoint",
+          id: cpId,
+          tool: toolName,
+          tool_use_id: call.id,
+          turn_id: `${runId}:t${budget.consumed}`,
+        };
 
-      yield { type: "tool-executing", tool: toolName, args: toolArgs };
+      yield {
+        type: "tool-executing",
+        tool: toolName,
+        args: toolArgs,
+        tool_use_id: call.id,
+        turn_id: `${runId}:t${budget.consumed}`,
+      };
 
       let toolResult;
       let toolError = null;
@@ -8134,6 +8463,12 @@ export async function* agentLoop(messages, options) {
         tool: toolName,
         result: toolResult,
         error: toolError,
+        tool_use_id: call.id,
+        turn_id: `${runId}:t${budget.consumed}`,
+        permission_decision_id: permissionDecisionId(
+          call.id,
+          toolResult?.policy,
+        ),
       };
 
       messages.push({