chainlesschain 0.162.180 → 0.162.182

package/src/runtime/agent-core.js

@@ -93,6 +93,8 @@ import {
   formatProviderHttpError,
   formatProviderResponseError,
 } from "../lib/provider-http-error.js";
+import { buildPermissionDecision } from "../lib/permission-decision.js";
+import { resolveSandboxPolicyPath } from "../lib/agent-sandbox.js";
 
 export { formatProviderHttpError };
 
@@ -149,6 +151,56 @@ function runCodeProcess(file, args, options = {}, origin = "run-code") {
   });
 }
 
+function collectWorkspacePluginBinSandboxPolicy(
+  pluginBin,
+  workspaceCwd,
+  executionCwd = workspaceCwd,
+) {
+  const resolvedWorkspaceCwd = path.resolve(workspaceCwd);
+  const pluginPolicyBoundaries = new Set();
+  for (const policyCwd of new Set([
+    resolvedWorkspaceCwd,
+    path.resolve(executionCwd),
+  ])) {
+    const observedPolicy = pluginBin.collectPluginBinSandboxPolicy({
+      cwd: policyCwd,
+    });
+    for (const boundary of observedPolicy?.requiredBoundaries || []) {
+      pluginPolicyBoundaries.add(boundary);
+    }
+  }
+  return pluginBin.pinPluginBinSandboxPolicy(
+    { requiredBoundaries: [...pluginPolicyBoundaries] },
+    { cwd: resolvedWorkspaceCwd },
+  );
+}
+
+function rethrowRunCodeSandboxFailure(error) {
+  if (
+    error?.sandboxFailClosed === true ||
+    (typeof error?.code === "string" &&
+      error.code.startsWith("ERR_PROCESS_SANDBOX"))
+  ) {
+    throw error;
+  }
+}
+
+function createPythonInterpreterProbeSandboxFailure(sandboxPolicy) {
+  const requiredBoundaries = [...(sandboxPolicy?.requiredBoundaries || [])];
+  const error = new Error(
+    `Python interpreter discovery cannot run without its required sandbox boundaries: ${requiredBoundaries.join(", ")}`,
+  );
+  error.code = "ERR_PROCESS_SANDBOX_BOUNDARY_UNSATISFIED";
+  error.sandboxReason = "python_interpreter_probe_requires_sandbox";
+  error.sandboxFailClosed = true;
+  error.requiredBoundaries = requiredBoundaries;
+  error.actualGuarantees = [];
+  error.missingBoundaries = [...requiredBoundaries];
+  error.sandboxBackend = null;
+  error.sandboxCandidateBackend = null;
+  return error;
+}
+
 // ─── Background shell tasks ────────────────────────────────────────────────
 //
 // run_shell is synchronous (execSync) and capped at a foreground timeout, which
@@ -837,6 +889,10 @@ export function getCachedPython() {
   return _cachedPython;
 }
 
+export function _resetCachedPythonForTests() {
+  _cachedPython = null;
+}
+
 /**
  * Gather environment info (cached once per process).
  * @returns {{ os: string, arch: string, python: string|null, pip: boolean, node: string|null, git: boolean }}
@@ -1172,6 +1228,89 @@ const GUARDED_FILE_MUTATION_TOOLS = new Set([
   "notebook_edit",
 ]);
 
+function agentFileToolPathRequests(name, args = {}, workspaceRoots = []) {
+  const one = (argument, access) =>
+    typeof args[argument] === "string" && args[argument].length > 0
+      ? [{ argument, path: args[argument], access }]
+      : [];
+  switch (name) {
+    case "read_file":
+      return one("path", "read");
+    case "write_file":
+    case "edit_file":
+    case "edit_file_hashed":
+    case "delete_file":
+    case "notebook_edit":
+      return one("path", "write");
+    case "move_file":
+      return [...one("path", "write"), ...one("target_path", "write")];
+    case "list_dir":
+      return [
+        {
+          argument: "path",
+          path:
+            typeof args.path === "string" && args.path.length > 0
+              ? args.path
+              : ".",
+          access: "read",
+        },
+      ];
+    case "search_files":
+      return typeof args.directory === "string" && args.directory.length > 0
+        ? [
+            {
+              argument: "directory",
+              path: args.directory,
+              access: "read",
+            },
+          ]
+        : workspaceRoots.map((root) => ({
+            argument: "directory",
+            path: root,
+            access: "read",
+          }));
+    case "code_intelligence":
+      return args.action === "workspace_symbols"
+        ? workspaceRoots.map((root) => ({
+            argument: "file",
+            path: root,
+            access: "read",
+          }))
+        : one("file", "read");
+    case "publish_artifact":
+      return one("path", "read");
+    default:
+      return [];
+  }
+}
+
+function guardAgentFileToolPaths(name, args, context, cwd) {
+  const workspaceRoots = workspaceRootsFor(cwd, context.additionalDirectories);
+  const requests = agentFileToolPathRequests(name, args || {}, workspaceRoots);
+  for (const request of requests) {
+    const verdict = resolveSandboxPolicyPath(request.path, {
+      access: request.access,
+      cwd,
+      workspaceRoots,
+      sandbox: context.sandbox || null,
+    });
+    if (!verdict.ok) {
+      return {
+        error:
+          `[Workspace Path Guard] ${name}.${request.argument} ` +
+          `"${request.path}" was blocked: ${verdict.error}.`,
+        policy: {
+          decision: "deny",
+          via: "workspace-path-guard",
+          reason: verdict.reason,
+          access: request.access,
+        },
+      };
+    }
+  }
+  return null;
+}
+
 function fileMutationPaths(name, args = {}) {
   return [
     args.path,
@@ -1553,6 +1692,16 @@ export async function executeTool(name, args, context = {}) {
     }
     context = { ...context, toolAttribution: attribution };
   }
+
+  // Built-in file tools are confined to the declared workspace roots even
+  // when no process sandbox is enabled. Resolve existing targets (and the
+  // nearest existing parent for creates) through symlinks/junctions before any
+  // permission hook, IDE preview, credential check, or filesystem operation
+  // can touch them. Explicit --add-dir roots and sandbox allowRead/allowWrite
+  // paths are the only supported expansions beyond cwd; deny paths still win.
+  const workspacePathDenial = guardAgentFileToolPaths(name, args, context, cwd);
+  if (workspacePathDenial) return workspacePathDenial;
+
   const toolContext = createToolContext({
     toolName: runtimeDescriptor?.name || name,
     cwd,
@@ -2758,6 +2907,39 @@ async function filterSkillsByCwd(skills, cwd) {
   }
 }
 
+async function promoteBrowserScreenshot(
+  filePath,
+  { sessionId = null, title = "Browser screenshot" } = {},
+) {
+  if (!filePath) return { artifact: null, error: null };
+  try {
+    const { ArtifactStore, publicArtifactMetadata } =
+      await import("../lib/artifact-store.js");
+    const entry = new ArtifactStore().publish({
+      filePath,
+      title,
+      kind: "screenshot",
+      sessionId: sessionId ? String(sessionId) : null,
+    });
+    return { artifact: publicArtifactMetadata(entry), error: null };
+  } catch (err) {
+    const code =
+      typeof err?.code === "string"
+        ? err.code.replace(/[^A-Z0-9_-]/gi, "").slice(0, 40)
+        : "";
+    return {
+      artifact: null,
+      error: `browser screenshot artifact publication failed${code ? ` (${code})` : ""}`,
+    };
+  } finally {
+    try {
+      fs.rmSync(filePath, { force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+}
+
 async function executeToolInner(
   name,
   args,
@@ -3337,25 +3519,117 @@ async function executeToolInner(
           : {}
         : { shell: shellInv.kind };
 
-      // PATH-based plugin binaries need explicit provenance at the Broker
-      // boundary; otherwise a trusted plugin executable is indistinguishable
-      // from an ambient system command in the process audit log.
-      let pluginBinProvenance = null;
+      // Policy-bearing plugin bins never enter PATH. Their declared alias is
+      // accepted only as one direct command: resolve it to literal argv, attest
+      // the exact target, then give Broker an absolute command with shell:false.
+      // Resolver failures for a matching strict alias are terminal — falling
+      // back to a shell would bypass target identity and manifest requirements.
+      let pluginBinInvocation = null;
+      let reattestPluginBinInvocation = null;
+      let pluginBinSandboxPolicy = null;
+      let pluginBinSandboxExecutionContract = null;
       try {
-        const { resolvePluginBinCommand } =
-          await import("../lib/plugin-runtime/bin.js");
-        pluginBinProvenance = resolvePluginBinCommand(args.command, { cwd });
-      } catch {
-        pluginBinProvenance = null;
+        const pluginBin = await import("../lib/plugin-runtime/bin.js");
+        reattestPluginBinInvocation = pluginBin.reattestPluginBinInvocation;
+        pluginBinSandboxPolicy = collectWorkspacePluginBinSandboxPolicy(
+          pluginBin,
+          cwd,
+          args.cwd || cwd,
+        );
+        pluginBinInvocation = pluginBin.resolvePluginBinInvocation(
+          args.command,
+          {
+            cwd,
+            commandCwd: args.cwd || cwd,
+          },
+        );
+        if (pluginBinInvocation?.sandboxPolicy) {
+          pluginBinSandboxPolicy = pluginBin.pinPluginBinSandboxPolicy(
+            {
+              requiredBoundaries: [
+                ...(pluginBinSandboxPolicy?.requiredBoundaries || []),
+                ...(pluginBinInvocation.sandboxPolicy.requiredBoundaries || []),
+              ],
+            },
+            { cwd },
+          );
+          if (
+            process.platform === "linux" ||
+            (process.platform === "win32" &&
+              pluginBinInvocation.runtime === "node")
+          ) {
+            try {
+              pluginBinSandboxExecutionContract =
+                pluginBin.createPluginSandboxExecutionContract(
+                  pluginBinInvocation,
+                );
+            } catch (error) {
+              if (error?.pluginBinFailClosed) throw error;
+              const contractError = new Error(
+                `plugin sandbox execution contract could not be created: ${error.message}`,
+              );
+              contractError.code = "ERR_PLUGIN_SANDBOX_CONTRACT_UNATTESTED";
+              contractError.pluginBinFailClosed = true;
+              throw contractError;
+            }
+          }
+        }
+      } catch (err) {
+        if (err?.pluginBinFailClosed) {
+          const policyVia =
+            err.code === "ERR_PLUGIN_BIN_DISCOVERY_FAILED"
+              ? "plugin-bin-pinned-sandbox-policy"
+              : "plugin-bin-direct-invocation";
+          return attachDescriptor(
+            {
+              error: `[Plugin bin] ${err.message}`,
+              policy: {
+                decision: "deny",
+                via: policyVia,
+                reason: err.code || "plugin_bin_resolution_failed",
+              },
+              shellCommandPolicy: shellPolicy,
+              approval: approvalOutcome,
+            },
+            override || runtimeDescriptor,
+          );
+        }
+        pluginBinInvocation = null;
       }
-      const processOrigin = pluginBinProvenance
+      const processOrigin = pluginBinInvocation
         ? "plugin:bin"
         : "tool:run_shell";
-      const processProvenance = pluginBinProvenance
+      const processProvenance = {
+        ...(pluginBinInvocation
+          ? {
+              pluginId: pluginBinInvocation.pluginId,
+              pluginVersion: pluginBinInvocation.pluginVersion,
+              pluginSource: pluginBinInvocation.pluginSource,
+              pluginExecutableIdentity: pluginBinInvocation.executableIdentity,
+            }
+          : {}),
+        ...(pluginBinSandboxPolicy
+          ? { sandboxPolicy: pluginBinSandboxPolicy }
+          : {}),
+        ...(pluginBinSandboxExecutionContract
+          ? {
+              sandboxExecutionContract: pluginBinSandboxExecutionContract,
+            }
+          : {}),
+      };
+      const pluginBinResult = pluginBinInvocation
         ? {
-            pluginId: pluginBinProvenance.pluginId,
-            pluginVersion: pluginBinProvenance.pluginVersion,
-            pluginSource: pluginBinProvenance.pluginSource,
+            plugin_bin: {
+              plugin: pluginBinInvocation.pluginId,
+              version: pluginBinInvocation.pluginVersion,
+              name: pluginBinInvocation.binName,
+              target: pluginBinInvocation.binPath,
+              runtime: pluginBinInvocation.runtime,
+              sha256: pluginBinInvocation.executableIdentity.sha256,
+              identity_attested: true,
+              launch_identity_reattested: false,
+              direct_argv: true,
+            },
           }
         : {};
 
@@ -3370,6 +3644,23 @@ async function executeToolInner(
             policy: { decision: "deny", via: "sandbox" },
           });
         }
+        if (
+          (process.platform === "linux" || process.platform === "win32") &&
+          pluginBinSandboxPolicy?.requiredBoundaries?.length > 0
+        ) {
+          return attachDescriptor({
+            error:
+              "[Plugin bin] The current strong plugin boundary supports foreground execution only; background execution is fail-closed until Broker-owned process-tree teardown is available.",
+            policy: {
+              decision: "deny",
+              via: "plugin-bin-pinned-sandbox-policy",
+              reason: "background_execution_unsupported",
+            },
+            ...pluginBinResult,
+            shellCommandPolicy: shellPolicy,
+            approval: approvalOutcome,
+          });
+        }
         // Free memory from idle background tasks before adding another, so a
         // long agent run can't accumulate forgotten dev servers (no-op unless
         // the machine is actually under memory pressure).
@@ -3425,9 +3716,29 @@ async function executeToolInner(
             scope: "agent",
             ...processProvenance,
           };
-          const child = shellInv.useDefaultShell
-            ? broker.spawn(args.command, [], brokerOpts)
-            : broker.spawn(shellInv.file, shellInv.argv, brokerOpts);
+          let child;
+          if (pluginBinInvocation) {
+            reattestPluginBinInvocation(pluginBinInvocation);
+            pluginBinResult.plugin_bin.launch_identity_reattested = true;
+            child = broker.spawn(
+              pluginBinSandboxExecutionContract?.kind ===
+                "strict-plugin-node-bin"
+                ? pluginBinSandboxExecutionContract.runtimePath
+                : pluginBinInvocation.command,
+              pluginBinInvocation.args,
+              {
+                ...brokerOpts,
+                cwd:
+                  pluginBinSandboxExecutionContract?.workingDirectory ||
+                  brokerOpts.cwd,
+                shell: false,
+              },
+            );
+          } else {
+            child = shellInv.useDefaultShell
+              ? broker.spawn(args.command, [], brokerOpts)
+              : broker.spawn(shellInv.file, shellInv.argv, brokerOpts);
+          }
           task.child = child;
           if (child.stdout) {
             child.stdout.setEncoding("utf8");
@@ -3478,6 +3789,7 @@ async function executeToolInner(
             status: task.status,
             command: task.command,
             ...shellMeta,
+            ...pluginBinResult,
             hint: "Poll output and completion with the check_shell tool using this task_id. Kill long-lived servers with check_shell { task_id, kill: true } when done.",
             shellCommandPolicy: shellPolicy,
             approval: approvalOutcome,
@@ -3487,6 +3799,23 @@ async function executeToolInner(
       }
 
       if (sandbox) {
+        if (pluginBinSandboxPolicy) {
+          return attachDescriptor(
+            {
+              error:
+                "[Plugin bin] A strict plugin bin policy cannot be combined with the legacy ephemeral shell sandbox. Run without that sandbox so the ProcessExecutionBroker can enforce the pinned plugin boundary union.",
+              policy: {
+                decision: "deny",
+                via: "plugin-bin-pinned-sandbox-policy",
+                reason: "conflicting_sandbox_routes",
+              },
+              ...pluginBinResult,
+              shellCommandPolicy: shellPolicy,
+              approval: approvalOutcome,
+            },
+            override || runtimeDescriptor,
+          );
+        }
         const { executeSandboxedShell, sandboxSummary } =
           await import("../lib/agent-sandbox.js");
         // Domain-restricted networking is ENFORCED by routing the sandboxed
@@ -3607,7 +3936,35 @@ async function executeToolInner(
           scope: "agent",
           ...processProvenance,
         };
-        if (shellInv.useDefaultShell) {
+        if (pluginBinInvocation) {
+          reattestPluginBinInvocation(pluginBinInvocation);
+          pluginBinResult.plugin_bin.launch_identity_reattested = true;
+          const res = broker.spawnSync(
+            pluginBinSandboxExecutionContract?.kind === "strict-plugin-node-bin"
+              ? pluginBinSandboxExecutionContract.runtimePath
+              : pluginBinInvocation.command,
+            pluginBinInvocation.args,
+            {
+              ...brokerExecOpts,
+              cwd:
+                pluginBinSandboxExecutionContract?.workingDirectory ||
+                brokerExecOpts.cwd,
+              shell: false,
+              windowsHide: true,
+            },
+          );
+          if (res.error) throw res.error;
+          if (res.status !== 0) {
+            const e = new Error(
+              `Plugin bin failed (exit ${res.status}): ${pluginBinInvocation.binName}`,
+            );
+            e.status = res.status;
+            e.stdout = res.stdout;
+            e.stderr = res.stderr;
+            throw e;
+          }
+          output = res.stdout ?? "";
+        } else if (shellInv.useDefaultShell) {
           output = broker.execSync(args.command, brokerExecOpts);
         } else {
           // PowerShell route: explicit argv, no intermediate default shell.
@@ -3649,6 +4006,7 @@ async function executeToolInner(
           {
             stdout: output.substring(0, 30000),
             ...shellMeta,
+            ...pluginBinResult,
             shellCommandPolicy: shellPolicy,
             approval: approvalOutcome,
           },
@@ -3669,6 +4027,7 @@ async function executeToolInner(
             stderr: (err.stderr || "").substring(0, 2000),
             exitCode: err.status,
             ...shellMeta,
+            ...pluginBinResult,
             shellCommandPolicy: shellPolicy,
             approval: approvalOutcome,
           },
@@ -4181,6 +4540,9 @@ async function executeToolInner(
             : 60000;
           const entry = store.createMonitor({
             command: args.command,
+            // Bind the persisted command to the host/session workspace. This
+            // value comes from executeTool's trusted context, never model args.
+            workspaceCwd: path.resolve(cwd),
             intervalMs,
             stopWhen: args.stop_when || null,
             notify: args.notify_title ? { title: args.notify_title } : null,
@@ -4219,7 +4581,8 @@ async function executeToolInner(
       // Only METADATA returns to the conversation (the transcript never
       // carries the file body); `cc artifacts` lists/inspects/cleans.
       try {
-        const { ArtifactStore } = await import("../lib/artifact-store.js");
+        const { ArtifactStore, publicArtifactMetadata } =
+          await import("../lib/artifact-store.js");
         const store = new ArtifactStore();
         const entry = store.publish({
           filePath: path.resolve(cwd, String(args.path || "")),
@@ -4229,7 +4592,7 @@ async function executeToolInner(
           sessionId: sessionId ? String(sessionId) : null,
         });
         return attachDescriptor({
-          published: entry,
+          published: publicArtifactMetadata(entry),
           hint: "The user can browse this with `cc artifacts list` / `cc artifacts show <id>`.",
         });
       } catch (err) {
@@ -4265,7 +4628,25 @@ async function executeToolInner(
             error: `browser_state failed: ${state.error}`,
           });
         }
-        return attachDescriptor(state);
+        const safeState = { ...state };
+        if (state.screenshotPath) {
+          const promoted = await promoteBrowserScreenshot(
+            state.screenshotPath,
+            {
+              sessionId,
+              title: `Browser state — ${state.title || "page"}`,
+            },
+          );
+          delete safeState.screenshotPath;
+          delete safeState.screenshotRef;
+          if (promoted.artifact) {
+            safeState.screenshotArtifact = promoted.artifact;
+            safeState.screenshotRef = promoted.artifact.id;
+          } else {
+            safeState.screenshotArtifactError = promoted.error;
+          }
+        }
+        return attachDescriptor(safeState);
       } catch (err) {
         return attachDescriptor({
           error: `browser_state failed: ${err.message}`,
@@ -4336,7 +4717,32 @@ async function executeToolInner(
             error: `browser_act failed: ${result.error}`,
           });
         }
-        return attachDescriptor(result);
+        const safeResult = { ...result, steps: [] };
+        for (let i = 0; i < (result.steps || []).length; i += 1) {
+          const originalStep = result.steps[i];
+          const step = { ...originalStep };
+          if (originalStep.screenshotPath) {
+            const promoted = await promoteBrowserScreenshot(
+              originalStep.screenshotPath,
+              {
+                sessionId,
+                title: `Browser action screenshot ${i + 1}`,
+              },
+            );
+            delete step.screenshotPath;
+            delete step.screenshotRef;
+            if (promoted.artifact) {
+              step.screenshotArtifact = promoted.artifact;
+              step.screenshotRef = promoted.artifact.id;
+              step.detail = `screenshot artifact: ${promoted.artifact.id}`;
+            } else {
+              step.screenshotArtifactError = promoted.error;
+              step.detail = promoted.error;
+            }
+          }
+          safeResult.steps.push(step);
+        }
+        return attachDescriptor(safeResult);
       } catch (err) {
         return attachDescriptor({
           error: `browser_act failed: ${err.message}`,
@@ -4982,6 +5388,54 @@ async function _executeRunCode(args, cwd) {
     };
   }
 
+  // Every agent-generated interpreter process inherits the tighten-only union
+  // of strict Plugin bin boundaries visible from this workspace. Discover and
+  // pin it before creating a persistent directory, writing a temporary script,
+  // or probing an interpreter so discovery failure cannot fall through to an
+  // unbounded native spawn.
+  let pluginBinSandboxPolicy = null;
+  try {
+    const pluginBin = await import("../lib/plugin-runtime/bin.js");
+    pluginBinSandboxPolicy = collectWorkspacePluginBinSandboxPolicy(
+      pluginBin,
+      cwd,
+    );
+  } catch (error) {
+    return {
+      error: `[Plugin bin] ${error.message}`,
+      policy: {
+        decision: "deny",
+        via: "plugin-bin-pinned-sandbox-policy",
+        reason: error.code || "ERR_PLUGIN_BIN_SANDBOX_POLICY_DISCOVERY_FAILED",
+      },
+    };
+  }
+  const pluginBinSandboxOptions = pluginBinSandboxPolicy
+    ? { sandboxPolicy: pluginBinSandboxPolicy }
+    : {};
+
+  // cli-anything's Python discovery probes candidate executables through its
+  // own Broker call. That probe cannot inherit this run_code invocation's
+  // pinned Plugin sandbox policy, so never launch it when strict boundaries
+  // are required. A previously cached interpreter is safe to execute here
+  // because the real script (and any pip/retry process) still goes through
+  // runCodeProcess with the exact pinned policy below.
+  let cachedPythonInterpreter = null;
+  if (
+    lang === "python" &&
+    pluginBinSandboxPolicy?.requiredBoundaries?.length > 0
+  ) {
+    if (
+      _cachedPython?.found === true &&
+      typeof _cachedPython.command === "string" &&
+      _cachedPython.command.trim()
+    ) {
+      cachedPythonInterpreter = _cachedPython.command;
+    } else {
+      throw createPythonInterpreterProbeSandboxFailure(pluginBinSandboxPolicy);
+    }
+  }
+
   // Determine script path
   let scriptPath;
   if (persist) {
@@ -5004,8 +5458,12 @@ async function _executeRunCode(args, cwd) {
     // Determine interpreter
     let interpreter;
     if (lang === "python") {
-      const py = getCachedPython();
-      interpreter = py.found ? py.command : "python";
+      if (cachedPythonInterpreter) {
+        interpreter = cachedPythonInterpreter;
+      } else {
+        const py = getCachedPython();
+        interpreter = py.found ? py.command : "python";
+      }
     } else if (lang === "node") {
       interpreter = "node";
     } else {
@@ -5020,8 +5478,13 @@ async function _executeRunCode(args, cwd) {
         encoding: "utf8",
         timeout: timeoutSec * 1000,
         maxBuffer: 5 * 1024 * 1024,
+        ...pluginBinSandboxOptions,
       });
     } catch (err) {
+      // Broker boundary errors carry the required/actual/missing guarantees and
+      // backend attestation. Preserve that exact structured error for callers
+      // instead of flattening it into run_code's generic runtime classifier.
+      rethrowRunCodeSandboxFailure(err);
       const stderr = (err.stderr || "").toString();
       const message = err.message || "";
       const classified = classifyError(stderr, message, err.status, lang);
@@ -5113,6 +5576,36 @@ async function _executeRunCode(args, cwd) {
             /* unified audit must never affect the install itself */
           }
 
+          const autoInstallFailure = (installError) => {
+            recordInstallAudit({
+              package: packageName,
+              interpreter,
+              cwd,
+              outcome: "failed",
+              detail: (
+                installError.stderr ||
+                installError.message ||
+                ""
+              ).substring(0, 200),
+            });
+            auditUnifiedInstall(
+              "failed",
+              (installError.stderr || installError.message || "").substring(
+                0,
+                200,
+              ),
+            );
+            return {
+              error: (stderr || message).substring(0, 5000),
+              stderr: stderr.substring(0, 5000),
+              exitCode: err.status,
+              language: lang,
+              ...classified,
+              hint: `Failed to auto-install "${packageName}". ${(installError.stderr || installError.message || "").substring(0, 500)}`,
+              scriptPath: persist ? scriptPath : undefined,
+            };
+          };
+
           // Attempt pip install
           try {
             runCodeProcess(
@@ -5124,18 +5617,27 @@ async function _executeRunCode(args, cwd) {
                 timeout: 120000,
                 maxBuffer: 2 * 1024 * 1024,
                 stdio: ["pipe", "pipe", "pipe"],
+                ...pluginBinSandboxOptions,
               },
               "run-code-install",
             );
-            recordInstallAudit({
-              package: packageName,
-              interpreter,
-              cwd,
-              outcome: "installed",
-            });
-            auditUnifiedInstall("installed");
+          } catch (pipErr) {
+            const failure = autoInstallFailure(pipErr);
+            rethrowRunCodeSandboxFailure(pipErr);
+            return failure;
+          }
+          recordInstallAudit({
+            package: packageName,
+            interpreter,
+            cwd,
+            outcome: "installed",
+          });
+          auditUnifiedInstall("installed");
 
-            // Retry execution
+          // Keep retry separate from the install catch: either Broker call can
+          // carry an independently attested fail-closed boundary error, and
+          // neither may be flattened into the legacy auto-install result.
+          try {
             const retryStart = Date.now();
             const retryOutput = runCodeProcess(
               interpreter,
@@ -5145,6 +5647,7 @@ async function _executeRunCode(args, cwd) {
                 encoding: "utf8",
                 timeout: timeoutSec * 1000,
                 maxBuffer: 5 * 1024 * 1024,
+                ...pluginBinSandboxOptions,
               },
               "run-code-retry",
             );
@@ -5158,25 +5661,24 @@ async function _executeRunCode(args, cwd) {
               autoInstalled: [packageName],
               scriptPath: persist ? scriptPath : undefined,
             };
-          } catch (pipErr) {
-            recordInstallAudit({
-              package: packageName,
-              interpreter,
-              cwd,
-              outcome: "failed",
-              detail: (pipErr.stderr || pipErr.message || "").substring(0, 200),
-            });
-            auditUnifiedInstall(
-              "failed",
-              (pipErr.stderr || pipErr.message || "").substring(0, 200),
+          } catch (retryErr) {
+            rethrowRunCodeSandboxFailure(retryErr);
+            const retryStderr = (retryErr.stderr || "").toString();
+            const retryMessage = retryErr.message || "";
+            const retryClassified = classifyError(
+              retryStderr,
+              retryMessage,
+              retryErr.status,
+              lang,
             );
             return {
-              error: (stderr || message).substring(0, 5000),
-              stderr: stderr.substring(0, 5000),
-              exitCode: err.status,
+              error: (retryStderr || retryMessage).substring(0, 5000),
+              stderr: retryStderr.substring(0, 5000),
+              exitCode: retryErr.status,
               language: lang,
-              ...classified,
-              hint: `Failed to auto-install "${packageName}". ${(pipErr.stderr || pipErr.message || "").substring(0, 500)}`,
+              ...retryClassified,
+              hint: `Package "${packageName}" was installed, but the script retry failed.`,
+              autoInstalled: [packageName],
               scriptPath: persist ? scriptPath : undefined,
             };
           }
@@ -5297,7 +5799,7 @@ export function safeStringifyToolResult(value) {
   }
 }
 
-function emitToolHookLifecycle({
+export function emitToolHookLifecycle({
   tool,
   args,
   result,
@@ -5306,6 +5808,7 @@ function emitToolHookLifecycle({
   turnId = null,
   toolUseId = null,
   cwd = process.cwd(),
+  emit = emitHooksV2Event,
 }) {
   const failed = Boolean(error || result?.error);
   const base = {
@@ -5317,7 +5820,7 @@ function emitToolHookLifecycle({
     duration_ms: Number(result?.toolTelemetryRecord?.durationMs || 0),
     cwd,
   };
-  emitHooksV2Event(failed ? "PostToolUseFailure" : "PostToolUse", {
+  emit(failed ? "PostToolUseFailure" : "PostToolUse", {
     ...base,
     ...(failed
       ? {
@@ -5337,7 +5840,7 @@ function emitToolHookLifecycle({
       args?.targetPath ||
       args?.target_path ||
       null;
-    emitHooksV2Event("FileChanged", {
+    emit("FileChanged", {
       ...base,
       path: changedPath == null ? null : String(changedPath),
       operation: tool,
@@ -5346,6 +5849,32 @@ function emitToolHookLifecycle({
   return failed;
 }
 
+export function emitToolBatchHookLifecycle({
+  records = [],
+  sessionId = null,
+  turnId = null,
+  cwd = process.cwd(),
+  parallel = false,
+  emit = emitHooksV2Event,
+}) {
+  if (!Array.isArray(records) || records.length === 0) return null;
+  const failed = records.filter((record) => record?.failed === true).length;
+  const payload = {
+    schema_version: 1,
+    session_id: sessionId,
+    turn_id: turnId,
+    cwd,
+    parallel: parallel === true,
+    total: records.length,
+    succeeded: records.length - failed,
+    failed,
+    tool_names: records.map((record) => record?.tool || "(unknown)"),
+    tool_use_ids: records.map((record) => record?.toolUseId || null),
+  };
+  emit("PostToolBatch", payload);
+  return payload;
+}
+
 /**
  * Execute a spawn_sub_agent tool call.
  * Creates an isolated SubAgentContext, runs it, and returns only the summary.
@@ -7507,11 +8036,12 @@ function extractInitialPromptText(messages) {
  * recompute it. Not exported (no shim-parity impact) — only the telemetry seam
  * uses it.
  */
-function permissionDecisionId(callId, policy) {
-  if (!policy || typeof policy !== "object" || !policy.decision) return null;
-  const gate = policy.via || policy.decision;
-  const base = callId || "call";
-  return `${base}:perm:${gate}`;
+function permissionDecision(callId, tool, result) {
+  return buildPermissionDecision({
+    toolUseId: callId,
+    tool,
+    result,
+  });
 }
 
 export async function* agentLoop(messages, options) {
@@ -7931,6 +8461,14 @@ export async function* agentLoop(messages, options) {
                 // self-persist is best-effort
               }
             }
+            emitHooksV2Event("PostCompact", {
+              schema_version: 1,
+              trigger: "auto",
+              session_id: options.sessionId || null,
+              messages_after: messages.length,
+              stats,
+              cwd: options.cwd || process.cwd(),
+            });
             yield { type: "compaction", stats, runId };
           }
         }
@@ -8182,7 +8720,33 @@ export async function* agentLoop(messages, options) {
             },
             { cwd: options.cwd || process.cwd() },
           );
-        } catch (_err) {
+          const failures = (stopOutcome?.results || []).filter(
+            (result) =>
+              result?.nonBlockingError === true ||
+              result?.malformedDecision === true ||
+              result?.breakerOpen === true,
+          );
+          if (failures.length > 0) {
+            emitHooksV2Event("StopFailure", {
+              schema_version: 1,
+              session_id: options.sessionId || null,
+              run_id: runId,
+              phase: "stop-hook",
+              failures: failures.map((failure) => ({
+                command: failure.command || null,
+                exit_code: failure.exitCode ?? null,
+                reason: failure.reason || failure.error || null,
+              })),
+            });
+          }
+        } catch (error) {
+          emitHooksV2Event("StopFailure", {
+            schema_version: 1,
+            session_id: options.sessionId || null,
+            run_id: runId,
+            phase: "stop-hook",
+            reason: error?.message || String(error),
+          });
           stopOutcome = null; // never affect the run outcome
         }
         if (stopOutcome && stopOutcome.decision === "block") {
@@ -8243,6 +8807,8 @@ export async function* agentLoop(messages, options) {
       );
     if (parallelReads) {
       throwIfAborted(signal);
+      const turnId = `${runId}:t${budget.consumed}`;
+      const toolBatchRecords = [];
       // Kick every read off now; settle into {result,error} so an unawaited
       // promise can never surface as an unhandled rejection if the loop aborts
       // before it is consumed.
@@ -8277,6 +8843,21 @@ export async function* agentLoop(messages, options) {
         };
         const { result: toolResult, error: toolError } = await promise;
         throwIfAborted(signal);
+        const failed = emitToolHookLifecycle({
+          tool: call.function.name,
+          args: toolArgs,
+          result: toolResult,
+          error: toolError,
+          sessionId: options.sessionId || null,
+          turnId,
+          toolUseId: call.id,
+          cwd: options.cwd || process.cwd(),
+        });
+        toolBatchRecords.push({
+          tool: call.function.name,
+          toolUseId: call.id,
+          failed,
+        });
         const warningMsg = budget.toWarningMessage();
         const resultStr = capToolResultString(
           safeStringifyToolResult(toolResult),
@@ -8284,6 +8865,11 @@ export async function* agentLoop(messages, options) {
         const toolContent = warningMsg
           ? `${resultStr}\n\n${warningMsg}`
           : resultStr;
+        const decision = permissionDecision(
+          call.id,
+          call.function.name,
+          toolResult,
+        );
         yield {
           type: "tool-result",
           tool: call.function.name,
@@ -8291,10 +8877,8 @@ export async function* agentLoop(messages, options) {
           error: toolError,
           tool_use_id: call.id,
           turn_id: `${runId}:t${budget.consumed}`,
-          permission_decision_id: permissionDecisionId(
-            call.id,
-            toolResult?.policy,
-          ),
+          permission_decision_id: decision?.id || null,
+          permission_decision: decision,
         };
         messages.push({
           role: "tool",
@@ -8302,9 +8886,18 @@ export async function* agentLoop(messages, options) {
           tool_call_id: call.id,
         });
       }
+      emitToolBatchHookLifecycle({
+        records: toolBatchRecords,
+        sessionId: options.sessionId || null,
+        turnId,
+        cwd: options.cwd || process.cwd(),
+        parallel: true,
+      });
       continue; // all read results in place — back to the LLM call
     }
 
+    const turnId = `${runId}:t${budget.consumed}`;
+    const toolBatchRecords = [];
     for (const call of toolCalls) {
       throwIfAborted(signal);
       const fn = call?.function;
@@ -8318,6 +8911,21 @@ export async function* agentLoop(messages, options) {
       // malformed call.
       if (typeof toolName !== "string" || !toolName) {
         const reason = "malformed tool call: missing function name";
+        emitToolHookLifecycle({
+          tool: "(unknown)",
+          args: null,
+          result: { error: reason },
+          error: reason,
+          sessionId: options.sessionId || null,
+          turnId,
+          toolUseId: call?.id || null,
+          cwd: options.cwd || process.cwd(),
+        });
+        toolBatchRecords.push({
+          tool: "(unknown)",
+          toolUseId: call?.id || null,
+          failed: true,
+        });
         yield {
           type: "tool-result",
           tool: "(unknown)",
@@ -8413,14 +9021,14 @@ export async function* agentLoop(messages, options) {
             // (derived from the call + gate, so it's recomputable from the
             // tool-result's policy + tool_call_id) plus the low-cardinality
             // decision, letting a blocked tool span be tied to its decision.
-            const decId =
+            const decision =
               r && typeof r === "object"
-                ? permissionDecisionId(call.id, r.policy)
+                ? permissionDecision(call.id, toolName, r)
                 : null;
-            if (decId) {
+            if (decision?.id) {
               const permAttrs = buildTelemetryAttributes({
-                decisionId: decId,
-                "permission.decision": r.policy.decision,
+                decisionId: decision.id,
+                "permission.decision": decision.decision,
               });
               if (permAttrs["permission.decision_id"]) {
                 span.setAttribute(
@@ -8458,6 +9066,7 @@ export async function* agentLoop(messages, options) {
         ? `${resultStr}\n\n${warningMsg}`
         : resultStr;
 
+      const decision = permissionDecision(call.id, toolName, toolResult);
       yield {
         type: "tool-result",
         tool: toolName,
@@ -8465,10 +9074,8 @@ export async function* agentLoop(messages, options) {
         error: toolError,
         tool_use_id: call.id,
         turn_id: `${runId}:t${budget.consumed}`,
-        permission_decision_id: permissionDecisionId(
-          call.id,
-          toolResult?.policy,
-        ),
+        permission_decision_id: decision?.id || null,
+        permission_decision: decision,
       };
 
       messages.push({
@@ -8476,7 +9083,29 @@ export async function* agentLoop(messages, options) {
         content: toolContent,
         tool_call_id: call.id,
       });
+      const failed = emitToolHookLifecycle({
+        tool: toolName,
+        args: toolArgs,
+        result: toolResult,
+        error: toolError,
+        sessionId: options.sessionId || null,
+        turnId,
+        toolUseId: call.id,
+        cwd: options.cwd || process.cwd(),
+      });
+      toolBatchRecords.push({
+        tool: toolName,
+        toolUseId: call.id,
+        failed,
+      });
     }
+    emitToolBatchHookLifecycle({
+      records: toolBatchRecords,
+      sessionId: options.sessionId || null,
+      turnId,
+      cwd: options.cwd || process.cwd(),
+      parallel: false,
+    });
   }
 
   // Budget exhausted — flush any child usage the final iteration produced,