chainlesschain 0.164.0 → 0.165.2

package/src/runtime/agent-core.js

@@ -18,7 +18,7 @@ import fs from "fs";
 import path from "path";
 import broker from "../lib/process-execution-broker/index.js";
 import os from "os";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { isProxy } from "node:util/types";
 import sharedCodingAgentPolicy from "./coding-agent-policy.cjs";
 import sharedShellPolicy from "./coding-agent-shell-policy.cjs";
@@ -28,6 +28,12 @@ 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 {
+  commitShellApprovalSideEffects,
+  createShellExecutionDescriptor,
+  evaluateShellCommandWithApproval,
+  snapshotShellExecutionArgs,
+} from "../lib/shell-approval.js";
 import { describeBackgroundCommand } from "../lib/terminal-context.js";
 import { buildTelemetryAttributes } from "../lib/telemetry-ids.js";
 import {
@@ -230,6 +236,36 @@ function collectWorkspacePluginBinSandboxPolicy(
   );
 }
 
+function projectPluginBinInvocationAuthority(invocation) {
+  if (!invocation) return null;
+  const identity = invocation.executableIdentity || {};
+  return {
+    command: invocation.command || null,
+    runtime: invocation.runtime || null,
+    shell: invocation.shell === true,
+    pluginId: invocation.pluginId || null,
+    pluginVersion: invocation.pluginVersion || null,
+    pluginSource: invocation.pluginSource || null,
+    scope: invocation.scope || null,
+    binName: invocation.binName || null,
+    binPath: invocation.binPath || null,
+    pluginRoot: invocation.pluginRoot || null,
+    args: Array.isArray(invocation.args) ? [...invocation.args] : [],
+    requiredBoundaries: [
+      ...(invocation.sandboxPolicy?.requiredBoundaries || []),
+    ].sort(),
+    executableIdentity: {
+      realPath: identity.realPath || null,
+      sha256: identity.sha256 || null,
+      bytes: identity.bytes ?? null,
+      dev: identity.dev ?? null,
+      ino: identity.ino ?? null,
+      mtimeMs: identity.mtimeMs ?? null,
+      mode: identity.mode ?? null,
+    },
+  };
+}
+
 function rethrowRunCodeSandboxFailure(error) {
   if (
     error?.sandboxFailClosed === true ||
@@ -2223,6 +2259,308 @@ function attachDiffReviewAudit(result, audit) {
   return result;
 }
 
+const RUN_CODE_ARGUMENT_KEYS = new Set([
+  "language",
+  "code",
+  "timeout",
+  "persist",
+]);
+
+function snapshotRunCodeExecutionArgs(args) {
+  if (
+    !args ||
+    typeof args !== "object" ||
+    Array.isArray(args) ||
+    isProxy(args)
+  ) {
+    throw new TypeError("run_code arguments must be a plain data object");
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(args);
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (typeof key !== "string" || !RUN_CODE_ARGUMENT_KEYS.has(key)) {
+      throw new TypeError(`run_code contains unsupported field ${String(key)}`);
+    }
+    if (!Object.hasOwn(descriptors[key], "value")) {
+      throw new TypeError(`run_code field ${key} must be a data property`);
+    }
+  }
+  const language = descriptors.language?.value;
+  const code = descriptors.code?.value;
+  if (typeof language !== "string" || !language) {
+    throw new TypeError("run_code language must be a non-empty string");
+  }
+  if (typeof code !== "string") {
+    throw new TypeError("run_code code must be a string");
+  }
+  const snapshot = { language, code };
+  if (descriptors.timeout) {
+    const timeout = descriptors.timeout.value;
+    if (typeof timeout !== "number" || !Number.isFinite(timeout)) {
+      throw new TypeError("run_code timeout must be a finite number");
+    }
+    snapshot.timeout = timeout;
+  }
+  if (descriptors.persist) {
+    const persist = descriptors.persist.value;
+    if (typeof persist !== "boolean") {
+      throw new TypeError("run_code persist must be a boolean");
+    }
+    snapshot.persist = persist;
+  }
+  return Object.freeze(snapshot);
+}
+
+function runCodeApprovalDescriptor(args, cwd) {
+  return Object.freeze({
+    language: args.language,
+    codeSha256: createHash("sha256").update(args.code, "utf8").digest("hex"),
+    codeBytes: Buffer.byteLength(args.code, "utf8"),
+    timeout: Math.min(Math.max(args.timeout || 60, 1), 300),
+    persist: args.persist === true,
+    cwd,
+  });
+}
+
+function canonicalPolicyAuthorityData(value, state = null, depth = 0) {
+  const budget = state || { nodes: 0, seen: new WeakSet() };
+  budget.nodes += 1;
+  if (budget.nodes > 4096 || depth > 12) {
+    throw new TypeError("policy authority exceeds canonical bounds");
+  }
+  if (value === null) return "null";
+  if (value === undefined) return '"$undefined"';
+  if (typeof value === "string" || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("policy authority contains a non-finite number");
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value !== "object" || isProxy(value)) {
+    throw new TypeError("policy authority must contain data objects only");
+  }
+  if (budget.seen.has(value)) {
+    throw new TypeError("policy authority must not contain cycles");
+  }
+  budget.seen.add(value);
+  try {
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const keys = Reflect.ownKeys(descriptors);
+    if (keys.some((key) => typeof key !== "string") || keys.length > 512) {
+      throw new TypeError("policy authority contains invalid keys");
+    }
+    if (Array.isArray(value)) {
+      const length = descriptors.length?.value;
+      if (!Number.isSafeInteger(length) || length < 0 || length > 512) {
+        throw new TypeError("policy authority array exceeds bounds");
+      }
+      const entries = [];
+      for (let index = 0; index < length; index += 1) {
+        const descriptor = descriptors[String(index)];
+        if (!descriptor || !Object.hasOwn(descriptor, "value")) {
+          throw new TypeError("policy authority arrays must be dense data");
+        }
+        entries.push(
+          canonicalPolicyAuthorityData(descriptor.value, budget, depth + 1),
+        );
+      }
+      const allowedKeys = new Set([
+        "length",
+        ...Array.from({ length }, (_, index) => String(index)),
+      ]);
+      if (keys.some((key) => !allowedKeys.has(key))) {
+        throw new TypeError("policy authority arrays contain extra fields");
+      }
+      return `[${entries.join(",")}]`;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError("policy authority must contain plain objects");
+    }
+    return `{${keys
+      .sort()
+      .map((key) => {
+        const descriptor = descriptors[key];
+        if (!Object.hasOwn(descriptor, "value")) {
+          throw new TypeError("policy authority accessors are not allowed");
+        }
+        return `${JSON.stringify(key)}:${canonicalPolicyAuthorityData(
+          descriptor.value,
+          budget,
+          depth + 1,
+        )}`;
+      })
+      .join(",")}}`;
+  } finally {
+    budget.seen.delete(value);
+  }
+}
+
+function digestPolicyAuthority(projection) {
+  return createHash("sha256")
+    .update("chainlesschain.shell-policy-authority.v1\0", "utf8")
+    .update(canonicalPolicyAuthorityData(projection), "utf8")
+    .digest("hex");
+}
+
+function validatePermissionRuleset(rules) {
+  if (!rules) return null;
+  if (typeof rules !== "object" || Array.isArray(rules)) {
+    throw new TypeError(
+      "permission authority provider returned an invalid ruleset",
+    );
+  }
+  const normalized = {};
+  for (const key of ["allow", "ask", "deny"]) {
+    const value = rules[key];
+    if (value !== undefined && !Array.isArray(value)) {
+      throw new TypeError(
+        "permission authority provider returned an invalid ruleset",
+      );
+    }
+    normalized[key] = value ? [...value] : [];
+  }
+  return normalized;
+}
+
+function projectPermissionAuthority({ authority, rules, tool, args, cwd }) {
+  const verdict = rules
+    ? evaluatePermissionRules({ tool, args, cwd, rules })
+    : { decision: null, rule: null };
+  const source = verdict.rule
+    ? authority?.sources?.[`${verdict.decision}:${verdict.rule}`] || null
+    : null;
+  const scopedRule = source?.startsWith("scoped:")
+    ? authority?.scoped?.rules?.find(
+        (record) =>
+          record.status === "active" && `scoped:${record.id}` === source,
+      ) || null
+    : null;
+  return {
+    rules: rules || null,
+    sources: authority?.sources || null,
+    scoped: authority?.scoped || null,
+    version: authority?.version || authority?.policyVersion || null,
+    revision: authority?.revision ?? null,
+    headHash: authority?.headHash || null,
+    verdict: {
+      decision: verdict.decision || null,
+      rule: verdict.rule || null,
+      source,
+      scopedRule: scopedRule
+        ? {
+            id: scopedRule.id || null,
+            revision: scopedRule.revision ?? null,
+            expiresAt: scopedRule.expiresAt ?? null,
+            status: scopedRule.status || null,
+          }
+        : null,
+    },
+  };
+}
+
+function selectedHostToolPolicy(hostAuthority, tool) {
+  const policies = hostAuthority?.tools || hostAuthority?.toolPolicies || null;
+  return policies && typeof policies === "object"
+    ? policies[tool] || null
+    : null;
+}
+
+function snapshotPlanToolAuthority(planManager, tool, args) {
+  const active = planManager?.isActive?.() === true;
+  return {
+    active,
+    executionLockActive: planManager?.executionLock != null,
+    toolAllowed:
+      !active || (tool === "git" && isReadOnlyGitCommand(args?.command))
+        ? true
+        : planManager?.isToolAllowed?.(tool) === true,
+  };
+}
+
+function snapshotEffectiveToolSetAuthority(effectiveAllowedToolNames, tool) {
+  const enforced = Array.isArray(effectiveAllowedToolNames);
+  return {
+    enforced,
+    allowed: !enforced || effectiveAllowedToolNames.includes(tool),
+  };
+}
+
+function evaluateSelectedToolAdmissionAuthority({
+  admission,
+  tool,
+  runtimeDescriptor,
+  localToolDescriptor,
+  hostManagedToolPolicy,
+}) {
+  if (admission?.enforce !== true) {
+    return {
+      override: {},
+      decision: null,
+      projection: { enforce: false },
+    };
+  }
+  const override =
+    admission.tools && typeof admission.tools === "object"
+      ? admission.tools[tool] || {}
+      : {};
+  const tier =
+    override.tier ||
+    runtimeDescriptor?.tier ||
+    getCodingAgentToolPolicy(tool)?.tier ||
+    (localToolDescriptor ? "extension" : "mvp");
+  const inputs = {
+    capabilityGranted:
+      override.capabilityGranted ?? admission.capabilityGranted,
+    policyAllowed:
+      override.policyAllowed ??
+      (hostManagedToolPolicy
+        ? (hostManagedToolPolicy?.tools ||
+            hostManagedToolPolicy?.toolPolicies ||
+            {})[tool]?.allowed !== false
+        : admission.policyAllowed),
+    permissionGranted:
+      override.permissionGranted ?? admission.permissionGranted,
+    budgetOk: override.budgetOk ?? admission.budgetOk,
+    uiSupported: override.uiSupported ?? admission.uiSupported,
+  };
+  const decision = admitTool({ tool, tier, ...inputs });
+  return {
+    override,
+    decision,
+    projection: {
+      enforce: true,
+      tier: decision.tier,
+      capabilityGranted: inputs.capabilityGranted === true,
+      policyAllowed: inputs.policyAllowed === true,
+      permissionGranted: inputs.permissionGranted === true,
+      budgetOk: inputs.budgetOk === true,
+      uiSupported: inputs.uiSupported === true,
+      admitted: decision.admitted === true,
+      unmet: [...decision.unmet],
+    },
+  };
+}
+
+function snapshotApprovalPolicyAuthority(approvalGate, sessionId) {
+  if (!approvalGate) return null;
+  const snapshot = approvalGate.getAuthorizationPolicySnapshot?.(sessionId);
+  if (snapshot && typeof snapshot.then === "function") {
+    throw new TypeError("approval policy snapshot must be synchronous");
+  }
+  if (snapshot) return snapshot;
+  return {
+    schema: "chainlesschain.approval-policy-authority/v1",
+    kind: "legacy-gate",
+    sessionId: sessionId ? String(sessionId) : null,
+    policy: approvalGate.getSessionPolicy?.(sessionId) || null,
+    hasAuthorizationConsumer:
+      approvalGate.hasAuthorizationConsumer?.() === true,
+  };
+}
+
 /**
  * Execute a single tool call with plan-mode filtering and hook pipeline.
  *
@@ -2235,9 +2573,99 @@ function attachDiffReviewAudit(result, audit) {
  * @returns {Promise<object>} tool result
  */
 export async function executeTool(name, args, context = {}) {
+  const liveExecutionContext = context;
+  // run_shell can cross several asynchronous permission/hook boundaries before
+  // reaching executeToolInner. Capture its declared tuple and working directory
+  // before any of them so an in-process caller cannot swap the approved command
+  // or reinterpret a relative cwd after process.chdir().
+  let shellAuthorityCwd = null;
+  let shellAuthorityWorkspaceCwd = null;
+  let runCodeAuthorityCwd = null;
+  if (name === "run_shell") {
+    try {
+      const entryProcessCwd = process.cwd();
+      const declared = snapshotShellExecutionArgs(args);
+      const contextCwd =
+        context.cwd === undefined || context.cwd === null
+          ? entryProcessCwd
+          : context.cwd;
+      if (typeof contextCwd !== "string" || !contextCwd) {
+        throw new TypeError("run_shell context cwd must be a non-empty string");
+      }
+      if (
+        declared.cwd !== undefined &&
+        (typeof declared.cwd !== "string" || !declared.cwd)
+      ) {
+        throw new TypeError("run_shell cwd must be a non-empty string");
+      }
+      shellAuthorityWorkspaceCwd = fs.realpathSync.native(
+        path.resolve(entryProcessCwd, contextCwd),
+      );
+      if (!fs.statSync(shellAuthorityWorkspaceCwd).isDirectory()) {
+        throw new Error("run_shell context cwd is not a directory");
+      }
+      const requestedCwd = path.resolve(
+        shellAuthorityWorkspaceCwd,
+        declared.cwd || ".",
+      );
+      shellAuthorityCwd = fs.realpathSync.native(requestedCwd);
+      if (!fs.statSync(shellAuthorityCwd).isDirectory()) {
+        throw new Error("run_shell cwd is not a directory");
+      }
+      args = snapshotShellExecutionArgs({
+        ...declared,
+        cwd: shellAuthorityCwd,
+      });
+    } catch (error) {
+      return {
+        error: `[Shell Dispatch] ${error?.message || "invalid execution arguments"}`,
+        policy: {
+          decision: "blocked",
+          via: "shell-execution-snapshot",
+          code: "CC_SHELL_EXECUTION_SNAPSHOT_INVALID",
+        },
+      };
+    }
+  }
+  if (name === "run_code") {
+    try {
+      const entryProcessCwd = process.cwd();
+      args = snapshotRunCodeExecutionArgs(args);
+      const contextCwd =
+        context.cwd === undefined || context.cwd === null
+          ? entryProcessCwd
+          : context.cwd;
+      if (typeof contextCwd !== "string" || !contextCwd) {
+        throw new TypeError("run_code context cwd must be a non-empty string");
+      }
+      runCodeAuthorityCwd = fs.realpathSync.native(
+        path.resolve(entryProcessCwd, contextCwd),
+      );
+      if (!fs.statSync(runCodeAuthorityCwd).isDirectory()) {
+        throw new Error("run_code cwd is not a directory");
+      }
+    } catch (error) {
+      return {
+        error: `[Run Code Dispatch] ${error?.message || "invalid execution arguments"}`,
+        policy: {
+          decision: "blocked",
+          via: "run-code-execution-snapshot",
+          code: "CC_RUN_CODE_EXECUTION_SNAPSHOT_INVALID",
+        },
+      };
+    }
+  }
   const hookDb = context.hookDb || null;
   const skillLoader = context.skillLoader || _defaultSkillLoader;
-  const cwd = context.cwd || process.cwd();
+  // Keep the authority-bearing workspace root distinct from the command's
+  // requested cwd. A command may run in a nested directory, but Plugin policy
+  // discovery and strong-sandbox issuance must remain anchored to the host
+  // workspace that admitted the tool call.
+  const cwd =
+    shellAuthorityWorkspaceCwd ||
+    runCodeAuthorityCwd ||
+    context.cwd ||
+    process.cwd();
   const planManager = context.planManager || getPlanModeManager();
   // The provider receives a filtered schema, but an untrusted/buggy model can
   // still emit an arbitrary tool_call. Reuse the same pure preflight that the
@@ -2247,6 +2675,27 @@ export async function executeTool(name, args, context = {}) {
     cwd,
   });
   if (authorityDenial) return authorityDenial;
+  let admittedEffectiveToolSetDigest = null;
+  if (name === "run_shell") {
+    try {
+      admittedEffectiveToolSetDigest = digestPolicyAuthority(
+        snapshotEffectiveToolSetAuthority(
+          context.effectiveAllowedToolNames,
+          name,
+        ),
+      );
+    } catch (error) {
+      return {
+        error:
+          "[Shell Dispatch] The effective tool capability ceiling could not be bound. No command side effect was started.",
+        policy: {
+          decision: "blocked",
+          via: "shell-policy-authority",
+          code: error?.code || "CC_SHELL_POLICY_AUTHORITY_UNAVAILABLE",
+        },
+      };
+    }
+  }
   const localToolDescriptor =
     context.externalToolDescriptors &&
     typeof context.externalToolDescriptors === "object"
@@ -2259,41 +2708,41 @@ export async function executeTool(name, args, context = {}) {
       : null;
   const runtimeDescriptor =
     getRuntimeToolDescriptor(name) || localToolDescriptor;
-  const admission = context.toolAdmission;
-  if (admission?.enforce === true) {
-    const override =
-      admission.tools && typeof admission.tools === "object"
-        ? admission.tools[name] || {}
-        : {};
-    const tier =
-      override.tier ||
-      runtimeDescriptor?.tier ||
-      getCodingAgentToolPolicy(name)?.tier ||
-      (localToolDescriptor ? "extension" : "mvp");
-    const decision = admitTool({
+  let admittedToolAdmissionDigest = null;
+  let toolAdmissionEvaluation;
+  try {
+    toolAdmissionEvaluation = evaluateSelectedToolAdmissionAuthority({
+      admission: context.toolAdmission,
       tool: name,
-      tier,
-      capabilityGranted:
-        override.capabilityGranted ?? admission.capabilityGranted,
-      policyAllowed:
-        override.policyAllowed ??
-        (context.hostManagedToolPolicy
-          ? (context.hostManagedToolPolicy?.tools ||
-              context.hostManagedToolPolicy?.toolPolicies ||
-              {})[name]?.allowed !== false
-          : admission.policyAllowed),
-      permissionGranted:
-        override.permissionGranted ?? admission.permissionGranted,
-      budgetOk: override.budgetOk ?? admission.budgetOk,
-      uiSupported: override.uiSupported ?? admission.uiSupported,
+      runtimeDescriptor,
+      localToolDescriptor,
+      hostManagedToolPolicy: context.hostManagedToolPolicy,
     });
+    if (name === "run_shell") {
+      admittedToolAdmissionDigest = digestPolicyAuthority(
+        toolAdmissionEvaluation.projection,
+      );
+    }
+  } catch (error) {
+    return {
+      error:
+        "[Tool Admission] The selected tool authority could not be bound. No tool side effect was started.",
+      policy: {
+        decision: "blocked",
+        via: "tool-admission",
+        code: error?.code || "CC_TOOL_ADMISSION_AUTHORITY_UNAVAILABLE",
+      },
+    };
+  }
+  if (toolAdmissionEvaluation.decision) {
+    const { override, decision } = toolAdmissionEvaluation;
     const attribution = buildToolAttribution({
       tool: name,
       source:
         override.source ||
         runtimeDescriptor?.source ||
         localToolDescriptor?.source ||
-        admission.source ||
+        context.toolAdmission?.source ||
         null,
       version: override.version || runtimeDescriptor?.version || null,
       scope: override.scope || localToolDescriptor?.scope || null,
@@ -2468,6 +2917,30 @@ export async function executeTool(name, args, context = {}) {
             : null,
     scopedRule: matchedScopedRule || null,
   };
+  let admittedPermissionPolicyDigest = null;
+  if (name === "run_shell") {
+    try {
+      admittedPermissionPolicyDigest = digestPolicyAuthority(
+        projectPermissionAuthority({
+          authority: permissionAuthority,
+          rules: validatePermissionRuleset(effectivePermissionRules),
+          tool: name,
+          args,
+          cwd,
+        }),
+      );
+    } catch (error) {
+      return {
+        error:
+          "[Shell Dispatch] The evaluated permission authority could not be bound. No command side effect was started.",
+        policy: {
+          decision: "blocked",
+          via: "shell-policy-authority",
+          code: error?.code || "CC_SHELL_POLICY_AUTHORITY_UNAVAILABLE",
+        },
+      };
+    }
+  }
 
   // 1. settings deny
   if (settingsVerdict.decision === "deny") {
@@ -2497,6 +2970,22 @@ export async function executeTool(name, args, context = {}) {
     toolPolicies && typeof toolPolicies === "object"
       ? toolPolicies[name]
       : null;
+  let admittedHostPolicyDigest = null;
+  if (name === "run_shell") {
+    try {
+      admittedHostPolicyDigest = digestPolicyAuthority(hostToolPolicy);
+    } catch (error) {
+      return {
+        error:
+          "[Shell Dispatch] The evaluated host policy could not be bound. No command side effect was started.",
+        policy: {
+          decision: "blocked",
+          via: "shell-policy-authority",
+          code: error?.code || "CC_SHELL_POLICY_AUTHORITY_UNAVAILABLE",
+        },
+      };
+    }
+  }
   const hostPolicyAllowsReadOnlyGit =
     name === "git" &&
     hostToolPolicy?.planModeBehavior === "readonly-conditional" &&
@@ -2530,6 +3019,24 @@ export async function executeTool(name, args, context = {}) {
     planManager.isActive() && !executionLockActive;
   const externalToolBlockedDuringPlanning =
     planReadOnlyFenceActive && !STATIC_AGENT_TOOL_NAMES.has(name);
+  let admittedPlanPolicyDigest = null;
+  if (name === "run_shell") {
+    try {
+      admittedPlanPolicyDigest = digestPolicyAuthority(
+        snapshotPlanToolAuthority(planManager, name, args),
+      );
+    } catch (error) {
+      return {
+        error:
+          "[Shell Dispatch] The evaluated plan authority could not be bound. No command side effect was started.",
+        policy: {
+          decision: "blocked",
+          via: "shell-policy-authority",
+          code: error?.code || "CC_SHELL_POLICY_AUTHORITY_UNAVAILABLE",
+        },
+      };
+    }
+  }
   context = { ...context, planReadOnlyFenceActive };
   if (
     planManager.isActive() &&
@@ -2828,6 +3335,160 @@ export async function executeTool(name, args, context = {}) {
     if (instructionPreflight) return instructionPreflight;
   }
 
+  let shellDispatchPolicyAuthority = null;
+  if (name === "run_shell") {
+    try {
+      const permissionRulesProvider = context.permissionRulesProvider || null;
+      const approvalGate = context.approvalGate || null;
+      const initialProjection = {
+        permission: projectPermissionAuthority({
+          authority: permissionAuthority,
+          rules: validatePermissionRuleset(effectivePermissionRules),
+          tool: name,
+          args,
+          cwd,
+        }),
+        host: selectedHostToolPolicy(
+          context.hostManagedToolPolicy || null,
+          name,
+        ),
+        plan: snapshotPlanToolAuthority(planManager, name, args),
+        effectiveToolSet: snapshotEffectiveToolSetAuthority(
+          context.effectiveAllowedToolNames,
+          name,
+        ),
+        toolAdmission: evaluateSelectedToolAdmissionAuthority({
+          admission: context.toolAdmission,
+          tool: name,
+          runtimeDescriptor,
+          localToolDescriptor,
+          hostManagedToolPolicy: context.hostManagedToolPolicy,
+        }).projection,
+        approval: snapshotApprovalPolicyAuthority(
+          approvalGate,
+          context.sessionId || null,
+        ),
+        unattended: context.unattendedActionPolicy || null,
+        shellPolicyOverrides: context.shellPolicyOverrides || null,
+        classifyAllShell: context.classifyAllShell === true,
+      };
+      if (
+        digestPolicyAuthority(initialProjection.permission) !==
+          admittedPermissionPolicyDigest ||
+        digestPolicyAuthority(initialProjection.host) !==
+          admittedHostPolicyDigest ||
+        digestPolicyAuthority(initialProjection.plan) !==
+          admittedPlanPolicyDigest ||
+        digestPolicyAuthority(initialProjection.effectiveToolSet) !==
+          admittedEffectiveToolSetDigest ||
+        digestPolicyAuthority(initialProjection.toolAdmission) !==
+          admittedToolAdmissionDigest
+      ) {
+        const error = new Error(
+          "Shell policy authority changed while an earlier confirmation was pending",
+        );
+        error.code = "CC_SHELL_POLICY_AUTHORITY_CHANGED";
+        throw error;
+      }
+      const initialDigest = digestPolicyAuthority(initialProjection);
+      shellDispatchPolicyAuthority = Object.freeze({
+        policyVersion: `cc-shell-policy-authority/v1:${initialDigest}`,
+        async revalidate() {
+          try {
+            if (
+              (liveExecutionContext.permissionRulesProvider || null) !==
+                permissionRulesProvider ||
+              (liveExecutionContext.approvalGate || null) !== approvalGate ||
+              (liveExecutionContext.planManager || getPlanModeManager()) !==
+                planManager
+            ) {
+              const error = new Error("policy authority provider changed");
+              error.code = "CC_SHELL_POLICY_AUTHORITY_CHANGED";
+              throw error;
+            }
+            let currentPermissionAuthority = null;
+            let currentPermissionRules =
+              liveExecutionContext.permissionRules || null;
+            if (permissionRulesProvider) {
+              currentPermissionAuthority = await permissionRulesProvider({
+                cwd,
+                tool: name,
+                args,
+              });
+              currentPermissionRules =
+                currentPermissionAuthority?.rules ||
+                currentPermissionAuthority ||
+                null;
+            }
+            const currentProjection = {
+              permission: projectPermissionAuthority({
+                authority: currentPermissionAuthority,
+                rules: validatePermissionRuleset(currentPermissionRules),
+                tool: name,
+                args,
+                cwd,
+              }),
+              host: selectedHostToolPolicy(
+                liveExecutionContext.hostManagedToolPolicy || null,
+                name,
+              ),
+              plan: snapshotPlanToolAuthority(planManager, name, args),
+              effectiveToolSet: snapshotEffectiveToolSetAuthority(
+                liveExecutionContext.effectiveAllowedToolNames,
+                name,
+              ),
+              toolAdmission: evaluateSelectedToolAdmissionAuthority({
+                admission: liveExecutionContext.toolAdmission,
+                tool: name,
+                runtimeDescriptor,
+                localToolDescriptor,
+                hostManagedToolPolicy:
+                  liveExecutionContext.hostManagedToolPolicy,
+              }).projection,
+              approval: snapshotApprovalPolicyAuthority(
+                approvalGate,
+                context.sessionId || null,
+              ),
+              unattended: liveExecutionContext.unattendedActionPolicy || null,
+              shellPolicyOverrides:
+                liveExecutionContext.shellPolicyOverrides || null,
+              classifyAllShell: liveExecutionContext.classifyAllShell === true,
+            };
+            if (digestPolicyAuthority(currentProjection) !== initialDigest) {
+              const error = new Error(
+                "Shell permission authority changed after initial admission",
+              );
+              error.code = "CC_SHELL_POLICY_AUTHORITY_CHANGED";
+              throw error;
+            }
+            return true;
+          } catch (error) {
+            if (error?.code === "CC_SHELL_POLICY_AUTHORITY_CHANGED") {
+              throw error;
+            }
+            const wrapped = new Error(
+              "Current shell permission authority could not be revalidated",
+              { cause: error },
+            );
+            wrapped.code =
+              error?.code || "CC_SHELL_POLICY_AUTHORITY_UNAVAILABLE";
+            throw wrapped;
+          }
+        },
+      });
+    } catch (error) {
+      return {
+        error:
+          "[Shell Dispatch] The current permission authority could not be bound. No command side effect was started.",
+        policy: {
+          decision: "blocked",
+          via: "shell-policy-authority",
+          code: error?.code || "CC_SHELL_POLICY_AUTHORITY_UNAVAILABLE",
+        },
+      };
+    }
+  }
+
   // PreToolUse hooks. DB hooks (cc hook add) stay observe-only — a failure
   // never blocks. settings.json hooks (context.settingsHooks) are decision-
   // capable: a `block` (exit 2 / {decision:block}) stops the tool here, an
@@ -2922,6 +3583,10 @@ export async function executeTool(name, args, context = {}) {
       sessionId: context.sessionId || null,
       turnId: context.turnId || null,
       toolCallId: context.toolCallId || null,
+      workflowEffectId: context.workflowEffectId || null,
+      workflowChildEffectId: context.workflowChildEffectId || null,
+      workflowChildSequence: context.workflowChildSequence || null,
+      workflowEffectProtocol: context.workflowEffectProtocol || 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
@@ -2951,12 +3616,14 @@ export async function executeTool(name, args, context = {}) {
       subtreeInstructionScope:
         context.subtreeInstructionScope || context.sessionId || "__legacy__",
       shellPolicyOverrides: context.shellPolicyOverrides || null,
+      classifyAllShell: context.classifyAllShell === true,
       approvalGate: context.approvalGate || null,
       shellConfirm: context.shellConfirm || null,
       additionalDirectories: context.additionalDirectories || null,
       sandbox: context.sandbox || null,
       ruleAllowed,
       settingsVerdict,
+      shellDispatchPolicyAuthority,
       subAgentDepth: context.subAgentDepth || 0,
       subAgentBudget: context.subAgentBudget || null,
       sessionBudget: context.sessionBudget || null,
@@ -4306,6 +4973,10 @@ async function executeToolInner(
     sessionId,
     turnId,
     toolCallId,
+    workflowEffectId = null,
+    workflowChildEffectId = null,
+    workflowChildSequence = null,
+    workflowEffectProtocol = null,
     planManager = null,
     permissionRules = null,
     effectiveAllowedToolNames = null,
@@ -4331,6 +5002,7 @@ async function executeToolInner(
     sandbox,
     ruleAllowed = false,
     settingsVerdict = null,
+    shellDispatchPolicyAuthority = null,
     subAgentDepth = 0,
     subAgentBudget = null,
     sessionBudget = null,
@@ -4812,6 +5484,9 @@ async function executeToolInner(
     }
 
     case "run_shell": {
+      // Bound the declared run_shell data once. Approval and dispatch never
+      // observe later mutation of the caller-owned tool arguments.
+      args = Object.isFrozen(args) ? args : snapshotShellExecutionArgs(args);
       if (unattendedActionPolicy?.unattended === true) {
         const unattendedVerdict = evaluateUnattendedShellAction(args.command, {
           ...unattendedActionPolicy,
@@ -4829,12 +5504,12 @@ async function executeToolInner(
         }
       }
 
-      const shellPolicyOpts = {
+      const shellPolicyOpts = Object.freeze({
         ...(shellPolicyOverrides
-          ? { overrideRuleIds: shellPolicyOverrides }
+          ? { overrideRuleIds: Object.freeze([...shellPolicyOverrides]) }
           : {}),
         ...(classifyAllShell ? { classifyAllShell: true } : {}),
-      };
+      });
       // Layer-by-layer explanation chain for a blocked command: which layers
       // were consulted and what each said (settings rules → shell policy →
       // approval gate). Attached to denial results so `/permissions denials`
@@ -4870,60 +5545,80 @@ async function executeToolInner(
         return chain;
       };
       const override = getRuntimeToolDescriptorByCommand(args.command);
-      let shellPolicy;
+      let shellPolicy = evaluateShellCommandPolicy(
+        args.command,
+        shellPolicyOpts,
+      );
       let approvalOutcome = null;
+      let approvalAuthorization = null;
+      let approvalAuthorizationContext = null;
+      let approvalGateResult = null;
       // A settings `allow` rule (ruleAllowed) pre-authorizes: skip the
       // ApprovalGate tier confirm, but still run the hard shell-policy denylist
       // below so an allow rule can never re-enable a blocked unsafe command.
-      if (approvalGate && !ruleAllowed) {
-        const { evaluateShellCommandWithApproval } =
-          await import("../lib/shell-approval.js");
-        const gated = await evaluateShellCommandWithApproval({
-          command: args.command,
-          sessionId,
-          approvalGate,
-          shellPolicyOptions: shellPolicyOpts,
-        });
-        shellPolicy = gated.shellPolicy;
-        approvalOutcome = {
-          decision: gated.decision,
-          via: gated.via,
-          riskLevel: gated.riskLevel,
-          policy: gated.policy,
-        };
-        if (!gated.allowed) {
-          // Make a policy denial ACTIONABLE for the model (Claude-Code 2.1.193
-          // "denial reasons to transcripts"): tell it this won't change on
-          // retry and to involve the user, so it stops re-issuing the same
-          // blocked command (which otherwise just burns turns + tokens).
-          const tierLabel =
-            typeof gated.policy === "string" ? `"${gated.policy}" ` : "";
-          return attachDescriptor(
-            {
-              error:
-                gated.via === "shell-policy"
-                  ? `[Shell Policy] ${gated.reason} This command is blocked by policy and will not run — do not retry it; find another approach.`
-                  : `[ApprovalGate] command denied by the ${tierLabel}approval policy (via ${gated.via}). Retrying the same command will not help — it needs user approval. Tell the user (they can run it themselves, approve it, or relax the policy) and continue with other work.`,
-              shellCommandPolicy: shellPolicy,
-              approval: approvalOutcome,
-              permissionChain: buildPermissionChain(gated),
-            },
-            override || runtimeDescriptor,
-          );
-        }
-      } else {
-        shellPolicy = evaluateShellCommandPolicy(args.command, shellPolicyOpts);
-        if (!shellPolicy.allowed) {
-          return attachDescriptor(
-            {
-              error: `[Shell Policy] ${shellPolicy.reason} This command is blocked by policy and will not run — do not retry it; find another approach.`,
-              shellCommandPolicy: shellPolicy,
-              permissionChain: buildPermissionChain(null),
-            },
-            override || runtimeDescriptor,
+      const requestShellApproval = async (operationArgs) => {
+        await shellDispatchPolicyAuthority?.revalidate?.();
+        if (approvalGate && !ruleAllowed) {
+          const approvalPolicyVersion = `${shellDispatchPolicyAuthority?.policyVersion || "cc-shell-policy-authority/v1:unobserved"}:shell:${shellPolicy.decision}:${shellPolicy.ruleId || "none"}`;
+          const gated = await evaluateShellCommandWithApproval({
+            command: args.command,
+            args: operationArgs,
+            sessionId,
+            approvalGate,
+            shellPolicyOptions: shellPolicyOpts,
+            workspace: args.cwd || cwd,
+            policyEnv: shellParentEnvironment,
+            policyVersion: approvalPolicyVersion,
+            deferSideEffects: true,
+          });
+          approvalGateResult = gated;
+          shellPolicy = gated.shellPolicy;
+          approvalOutcome = {
+            decision: gated.decision,
+            via: gated.via,
+            riskLevel: gated.riskLevel,
+            policy: gated.policy,
+          };
+          approvalAuthorization = gated.authorization;
+          approvalAuthorizationContext = gated.authorizationContext;
+          if (!gated.allowed) {
+            // Make a policy denial ACTIONABLE for the model (Claude-Code 2.1.193
+            // "denial reasons to transcripts"): tell it this won't change on
+            // retry and to involve the user, so it stops re-issuing the same
+            // blocked command (which otherwise just burns turns + tokens).
+            const tierLabel =
+              typeof gated.policy === "string" ? `"${gated.policy}" ` : "";
+            return attachDescriptor(
+              {
+                error:
+                  gated.via === "shell-policy"
+                    ? `[Shell Policy] ${gated.reason} This command is blocked by policy and will not run — do not retry it; find another approach.`
+                    : `[ApprovalGate] command denied by the ${tierLabel}approval policy (via ${gated.via}). Retrying the same command will not help — it needs user approval. Tell the user (they can run it themselves, approve it, or relax the policy) and continue with other work.`,
+                shellCommandPolicy: shellPolicy,
+                approval: approvalOutcome,
+                permissionChain: buildPermissionChain(gated),
+              },
+              override || runtimeDescriptor,
+            );
+          }
+        } else {
+          shellPolicy = evaluateShellCommandPolicy(
+            args.command,
+            shellPolicyOpts,
           );
+          if (!shellPolicy.allowed) {
+            return attachDescriptor(
+              {
+                error: `[Shell Policy] ${shellPolicy.reason} This command is blocked by policy and will not run — do not retry it; find another approach.`,
+                shellCommandPolicy: shellPolicy,
+                permissionChain: buildPermissionChain(null),
+              },
+              override || runtimeDescriptor,
+            );
+          }
         }
-      }
+        return null;
+      };
 
       // P1 #8 Windows/PowerShell first-class: per-call args.shell or the
       // configured settings `shell.windowsDefault` may route this command
@@ -4932,7 +5627,7 @@ async function executeToolInner(
       // the historical default shell byte-identical (useDefaultShell=true).
       const { resolveShellInvocation } =
         await import("../lib/shell-selector.cjs");
-      const shellInv = resolveShellInvocation({
+      let shellInv = resolveShellInvocation({
         command: args.command,
         requested: args.shell,
         cwd: args.cwd || cwd,
@@ -4949,12 +5644,16 @@ async function executeToolInner(
       // 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 pluginBinRuntime = null;
       let pluginBinSandboxPolicy = null;
       let pluginBinSandboxExecutionContract = null;
+      const backgroundPlatform =
+        typeof _backgroundProcessDeps.platform === "function"
+          ? _backgroundProcessDeps.platform()
+          : process.platform;
       try {
         const pluginBin = await import("../lib/plugin-runtime/bin.js");
-        reattestPluginBinInvocation = pluginBin.reattestPluginBinInvocation;
+        pluginBinRuntime = pluginBin;
         pluginBinSandboxPolicy = collectWorkspacePluginBinSandboxPolicy(
           pluginBin,
           cwd,
@@ -4978,8 +5677,8 @@ async function executeToolInner(
             { cwd },
           );
           if (
-            process.platform === "linux" ||
-            (process.platform === "win32" &&
+            backgroundPlatform === "linux" ||
+            (backgroundPlatform === "win32" &&
               pluginBinInvocation.runtime === "node")
           ) {
             try {
@@ -5024,7 +5723,7 @@ async function executeToolInner(
       const processOrigin = pluginBinInvocation
         ? "plugin:bin"
         : "tool:run_shell";
-      const processProvenance = {
+      let processProvenance = {
         ...(pluginBinInvocation
           ? {
               pluginId: pluginBinInvocation.pluginId,
@@ -5056,23 +5755,264 @@ async function executeToolInner(
               direct_argv: true,
             },
           }
-        : {};
+        : {};
+
+      // Snapshot process-derived execution inputs before confirmation. The
+      // descriptor carries only an opaque, secret-free environment reference;
+      // the actual child environment remains in this invocation-local closure.
+      const shellParentEnvironment = Object.freeze({ ...process.env });
+      const agentIdentityEnvironment = Object.freeze({
+        CLAUDECODE: "1",
+        ...(sessionId
+          ? {
+              CC_SESSION_ID: String(sessionId),
+              CLAUDE_CODE_SESSION_ID: String(sessionId),
+            }
+          : {}),
+      });
+      const credentialProxyResult = applyCredentialProxy(
+        {
+          ...shellParentEnvironment,
+          ...agentIdentityEnvironment,
+        },
+        { env: shellParentEnvironment },
+      );
+      const shellChildEnvironment = Object.freeze({
+        ...credentialProxyResult.env,
+      });
+      const sandboxChildEnvironment = agentIdentityEnvironment;
+      const shellExecutionDescriptor = createShellExecutionDescriptor({
+        args,
+        workspace: args.cwd || cwd,
+        shellInvocation: shellInv,
+        pluginInvocation: pluginBinInvocation,
+        pluginSandboxPolicy: pluginBinSandboxPolicy,
+        pluginSandboxExecutionContract: pluginBinSandboxExecutionContract,
+        sandbox,
+        environmentRef: {
+          id: `run-shell-env:${randomUUID()}`,
+          inheritance: sandbox ? "sandbox-minimal" : "host-snapshot",
+          credentialProxy: credentialProxyResult.enabled === true,
+          maskedNames: Object.freeze([...credentialProxyResult.masked]),
+        },
+      });
+      // From here onward the descriptor itself is the tool-argument snapshot.
+      args = shellExecutionDescriptor;
+      shellInv = shellExecutionDescriptor.execution.shell;
+      const shellSandbox = shellExecutionDescriptor.execution.sandbox;
+      const executionPlugin = shellExecutionDescriptor.execution.plugin;
+      const approvedPluginProjection = executionPlugin
+        ? canonicalPolicyAuthorityData(executionPlugin)
+        : null;
+      const approvedWorkspacePluginPolicy = canonicalPolicyAuthorityData(
+        pluginBinSandboxPolicy,
+      );
+      const approvedPluginInvocationAuthority = pluginBinInvocation
+        ? canonicalPolicyAuthorityData(
+            projectPluginBinInvocationAuthority(pluginBinInvocation),
+          )
+        : null;
+      const refreshPluginBinExecution = () => {
+        if (!executionPlugin) return;
+        if (!pluginBinRuntime) {
+          const error = new Error(
+            "Plugin bin runtime is unavailable during launch revalidation",
+          );
+          error.code = "ERR_PLUGIN_BIN_DISCOVERY_FAILED";
+          error.pluginBinFailClosed = true;
+          throw error;
+        }
+        const freshInvocation = pluginBinRuntime.resolvePluginBinInvocation(
+          shellExecutionDescriptor.command,
+          {
+            cwd,
+            commandCwd: shellExecutionDescriptor.cwd || cwd,
+            failClosed: true,
+          },
+        );
+        if (!freshInvocation) {
+          const error = new Error(
+            "Approved plugin bin alias is no longer available",
+          );
+          error.code = "ERR_PLUGIN_BIN_LAUNCH_AUTHORITY_CHANGED";
+          error.pluginBinFailClosed = true;
+          throw error;
+        }
+        if (
+          canonicalPolicyAuthorityData(
+            projectPluginBinInvocationAuthority(freshInvocation),
+          ) !== approvedPluginInvocationAuthority
+        ) {
+          const error = new Error(
+            "Plugin bin manifest, trust, alias, or sandbox authority changed after approval",
+          );
+          error.code = "ERR_PLUGIN_BIN_LAUNCH_AUTHORITY_CHANGED";
+          error.pluginBinFailClosed = true;
+          throw error;
+        }
+        let freshPolicy = collectWorkspacePluginBinSandboxPolicy(
+          pluginBinRuntime,
+          cwd,
+          shellExecutionDescriptor.cwd || cwd,
+        );
+        if (freshInvocation.sandboxPolicy) {
+          freshPolicy = pluginBinRuntime.pinPluginBinSandboxPolicy(
+            {
+              requiredBoundaries: [
+                ...(freshPolicy?.requiredBoundaries || []),
+                ...(freshInvocation.sandboxPolicy.requiredBoundaries || []),
+              ],
+            },
+            { cwd },
+          );
+        }
+        let freshContract = null;
+        if (
+          freshInvocation.sandboxPolicy &&
+          (backgroundPlatform === "linux" ||
+            (backgroundPlatform === "win32" &&
+              freshInvocation.runtime === "node"))
+        ) {
+          freshContract = pluginBinRuntime.createPluginSandboxExecutionContract(
+            freshInvocation,
+            { sync: shellExecutionDescriptor.run_in_background !== true },
+          );
+        }
+        const freshProjection = createShellExecutionDescriptor({
+          args: shellExecutionDescriptor,
+          workspace: shellExecutionDescriptor.execution.workspace,
+          shellInvocation: shellExecutionDescriptor.execution.shell,
+          pluginInvocation: freshInvocation,
+          pluginSandboxPolicy: freshPolicy,
+          pluginSandboxExecutionContract: freshContract,
+          sandbox: shellExecutionDescriptor.execution.sandbox,
+          environmentRef: shellExecutionDescriptor.execution.environment,
+        }).execution.plugin;
+        if (
+          canonicalPolicyAuthorityData(freshProjection) !==
+          approvedPluginProjection
+        ) {
+          const error = new Error(
+            "Plugin bin manifest, trust, alias, or sandbox authority changed after approval",
+          );
+          error.code = "ERR_PLUGIN_BIN_LAUNCH_AUTHORITY_CHANGED";
+          error.pluginBinFailClosed = true;
+          throw error;
+        }
+        pluginBinInvocation = freshInvocation;
+        pluginBinSandboxPolicy = freshPolicy;
+        pluginBinSandboxExecutionContract = freshContract;
+        processProvenance = {
+          pluginId: freshInvocation.pluginId,
+          pluginVersion: freshInvocation.pluginVersion,
+          pluginSource: freshInvocation.pluginSource,
+          pluginExecutableIdentity: freshInvocation.executableIdentity,
+          ...(freshPolicy ? { sandboxPolicy: freshPolicy } : {}),
+          ...(freshContract ? { sandboxExecutionContract: freshContract } : {}),
+        };
+      };
+      const refreshPluginExecutionAuthority = () => {
+        if (executionPlugin) {
+          refreshPluginBinExecution();
+          return;
+        }
+        if (!pluginBinRuntime) return;
+        const freshPolicy = collectWorkspacePluginBinSandboxPolicy(
+          pluginBinRuntime,
+          cwd,
+          shellExecutionDescriptor.cwd || cwd,
+        );
+        if (
+          canonicalPolicyAuthorityData(freshPolicy) !==
+          approvedWorkspacePluginPolicy
+        ) {
+          const error = new Error(
+            "Workspace plugin sandbox authority changed after approval",
+          );
+          error.code = "ERR_PLUGIN_BIN_LAUNCH_AUTHORITY_CHANGED";
+          error.pluginBinFailClosed = true;
+          throw error;
+        }
+        pluginBinSandboxPolicy = freshPolicy;
+        processProvenance = freshPolicy ? { sandboxPolicy: freshPolicy } : {};
+      };
+
+      const approvalDenial = await requestShellApproval(
+        shellExecutionDescriptor,
+      );
+      if (approvalDenial) return approvalDenial;
+
+      let shellDispatchAdmitted = false;
+      const admitShellDispatch = async () => {
+        if (shellDispatchAdmitted) {
+          throw new Error("Shell dispatch authorization was already consumed");
+        }
+        await shellDispatchPolicyAuthority?.revalidate?.();
+        refreshPluginExecutionAuthority();
+        const revalidated = evaluateShellCommandPolicy(
+          shellExecutionDescriptor.command,
+          shellPolicyOpts,
+        );
+        if (
+          !revalidated.allowed ||
+          revalidated.decision !== shellPolicy.decision ||
+          (revalidated.ruleId || null) !== (shellPolicy.ruleId || null)
+        ) {
+          const error = new Error(
+            "Shell policy changed after approval; command dispatch was denied",
+          );
+          error.code = "ERR_SHELL_POLICY_REVALIDATION_FAILED";
+          throw error;
+        }
+        if (approvalAuthorization) {
+          if (typeof approvalGate?.consumeAuthorization !== "function") {
+            throw new Error(
+              "Remote shell approval cannot be consumed by this ApprovalGate",
+            );
+          }
+          await approvalGate.consumeAuthorization(
+            approvalAuthorization,
+            approvalAuthorizationContext,
+          );
+          approvalAuthorization = null;
+        }
+        await shellDispatchPolicyAuthority?.revalidate?.();
+        refreshPluginExecutionAuthority();
+        const finalPolicy = evaluateShellCommandPolicy(
+          shellExecutionDescriptor.command,
+          shellPolicyOpts,
+        );
+        if (
+          !finalPolicy.allowed ||
+          finalPolicy.decision !== shellPolicy.decision ||
+          (finalPolicy.ruleId || null) !== (shellPolicy.ruleId || null)
+        ) {
+          const error = new Error(
+            "Shell policy changed while authorization was consumed; command dispatch was denied",
+          );
+          error.code = "ERR_SHELL_POLICY_REVALIDATION_FAILED";
+          throw error;
+        }
+        // Auditing is intentionally committed only after durable authorization
+        // consumption and immediately before the first external side effect.
+        commitShellApprovalSideEffects(approvalGateResult);
+        if (pluginBinInvocation) {
+          pluginBinResult.plugin_bin.launch_identity_reattested = true;
+        }
+        shellDispatchAdmitted = true;
+      };
 
       // Background: spawn, register, return a task_id immediately. The agent
       // polls output + completion via check_shell. No timeout — that's the whole
       // point of backgrounding (builds, test suites, dev servers).
       if (args.run_in_background === true) {
-        if (sandbox) {
+        if (shellSandbox) {
           return attachDescriptor({
             error:
               "[Sandbox] Background shell tasks are not supported in the ephemeral sandbox. Run in the foreground or explicitly disable --sandbox.",
             policy: { decision: "deny", via: "sandbox" },
           });
         }
-        const backgroundPlatform =
-          typeof _backgroundProcessDeps.platform === "function"
-            ? _backgroundProcessDeps.platform()
-            : process.platform;
         const pinnedBackgroundBoundaries = [
           ...(pluginBinSandboxPolicy?.requiredBoundaries || []),
         ];
@@ -5124,16 +6064,7 @@ async function executeToolInner(
             cwd: workingDirectory,
             shell: false,
             windowsHide: true,
-            env: applyCredentialProxy({
-              ...process.env,
-              CLAUDECODE: "1",
-              ...(sessionId
-                ? {
-                    CC_SESSION_ID: String(sessionId),
-                    CLAUDE_CODE_SESSION_ID: String(sessionId),
-                  }
-                : {}),
-            }).env,
+            env: shellChildEnvironment,
             detached: false,
             origin: "tool:run_shell",
             policy: "allow",
@@ -5188,6 +6119,9 @@ async function executeToolInner(
             },
           };
         }
+        // Admission precedes task cleanup, sequence allocation, listener
+        // registration, proxy startup and process creation.
+        await admitShellDispatch();
         // 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).
@@ -5199,7 +6133,7 @@ async function executeToolInner(
           cwd:
             linuxGenericBackgroundLaunch?.options.cwd ||
             (linuxDirectPluginStrongBackground
-              ? pluginBinSandboxExecutionContract.workingDirectory
+              ? executionPlugin.sandboxExecution.workingDirectory
               : args.cwd || cwd),
           status: "running",
           exitCode: null,
@@ -5230,16 +6164,7 @@ async function executeToolInner(
                 // Credential proxy (opt-in, CC_CREDENTIAL_PROXY): keeps the agent's
                 // real long-lived secrets out of the spawned command's env — a
                 // no-op (same object) when disabled. See credential-proxy.js.
-                env: applyCredentialProxy({
-                  ...process.env,
-                  CLAUDECODE: "1",
-                  ...(sessionId
-                    ? {
-                        CC_SESSION_ID: String(sessionId),
-                        CLAUDE_CODE_SESSION_ID: String(sessionId),
-                      }
-                    : {}),
-                }).env,
+                env: shellChildEnvironment,
                 // POSIX: own process group so check_shell{kill}/teardown can signal
                 // the whole tree (shell + its grandchild command). No-op on Windows
                 // where the tree is killed via taskkill /T instead.
@@ -5266,18 +6191,16 @@ async function executeToolInner(
               linuxGenericBackgroundLaunch.options,
             );
           } else if (pluginBinInvocation) {
-            reattestPluginBinInvocation(pluginBinInvocation);
-            pluginBinResult.plugin_bin.launch_identity_reattested = true;
             child = broker.spawn(
-              pluginBinSandboxExecutionContract?.kind ===
+              executionPlugin.sandboxExecution?.kind ===
                 "strict-plugin-node-bin"
-                ? pluginBinSandboxExecutionContract.runtimePath
-                : pluginBinInvocation.command,
-              pluginBinInvocation.args,
+                ? executionPlugin.sandboxExecution.runtimePath
+                : executionPlugin.command,
+              executionPlugin.argv,
               {
                 ...brokerOpts,
                 cwd:
-                  pluginBinSandboxExecutionContract?.workingDirectory ||
+                  executionPlugin.sandboxExecution?.workingDirectory ||
                   brokerOpts.cwd,
                 shell: false,
               },
@@ -5373,7 +6296,7 @@ async function executeToolInner(
         );
       }
 
-      if (sandbox) {
+      if (shellSandbox) {
         if (pluginBinSandboxPolicy) {
           return attachDescriptor(
             {
@@ -5391,15 +6314,16 @@ async function executeToolInner(
             override || runtimeDescriptor,
           );
         }
+        await admitShellDispatch();
         const { executeSandboxedShell, sandboxSummary } =
           await import("../lib/agent-sandbox.js");
         // Domain-restricted networking is ENFORCED by routing the sandboxed
         // process's egress through a local filtering proxy (see
         // sandbox-egress-proxy.js). Start it only when the policy actually
         // restricts domains and network is on; tear it down after the command.
-        const sboxPolicy = sandbox.policy || {};
+        const sboxPolicy = shellSandbox.policy || {};
         const needsEgress =
-          sandbox.network === true &&
+          shellSandbox.network === true &&
           (sboxPolicy.allowedDomains?.length || 0) +
             (sboxPolicy.deniedDomains?.length || 0) >
             0;
@@ -5428,20 +6352,25 @@ async function executeToolInner(
         }
         let result;
         try {
-          result = executeSandboxedShell(args.command, sandbox, {
+          // Proxy startup and dynamic imports are asynchronous. Re-read the
+          // live authority once more after they settle and immediately before
+          // the synchronous sandbox dispatch.
+          await shellDispatchPolicyAuthority?.revalidate?.();
+          refreshPluginExecutionAuthority();
+          if (pluginBinSandboxPolicy) {
+            const error = new Error(
+              "A plugin sandbox authority appeared while the legacy shell sandbox was starting",
+            );
+            error.code = "ERR_PLUGIN_BIN_SANDBOX_ROUTE_CONFLICT";
+            error.pluginBinFailClosed = true;
+            throw error;
+          }
+          result = executeSandboxedShell(args.command, shellSandbox, {
             cwd: args.cwd || cwd,
             timeout: _resolveShellTimeout(args.timeout),
             maxBuffer: 1024 * 1024,
             egressProxy,
-            env: {
-              CLAUDECODE: "1",
-              ...(sessionId
-                ? {
-                    CC_SESSION_ID: String(sessionId),
-                    CLAUDE_CODE_SESSION_ID: String(sessionId),
-                  }
-                : {}),
-            },
+            env: sandboxChildEnvironment,
           });
         } finally {
           if (proxyHandle) {
@@ -5453,7 +6382,7 @@ async function executeToolInner(
           }
         }
         const common = {
-          sandbox: sandboxSummary(sandbox),
+          sandbox: sandboxSummary(shellSandbox),
           shellCommandPolicy: shellPolicy,
           approval: approvalOutcome,
           policyTrace: ["shell-policy", "approval", "sandbox"],
@@ -5492,18 +6421,10 @@ async function executeToolInner(
           // Credential proxy (opt-in, CC_CREDENTIAL_PROXY): keeps the agent's
           // real long-lived secrets out of the shell's env — a no-op (same
           // object) when disabled. See credential-proxy.js.
-          env: applyCredentialProxy({
-            ...process.env,
-            CLAUDECODE: "1",
-            ...(sessionId
-              ? {
-                  CC_SESSION_ID: String(sessionId),
-                  CLAUDE_CODE_SESSION_ID: String(sessionId),
-                }
-              : {}),
-          }).env,
+          env: shellChildEnvironment,
         };
         let output;
+        await admitShellDispatch();
         const brokerExecOpts = {
           ...fgExecOpts,
           origin: processOrigin,
@@ -5512,17 +6433,15 @@ async function executeToolInner(
           ...processProvenance,
         };
         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,
+            executionPlugin.sandboxExecution?.kind === "strict-plugin-node-bin"
+              ? executionPlugin.sandboxExecution.runtimePath
+              : executionPlugin.command,
+            executionPlugin.argv,
             {
               ...brokerExecOpts,
               cwd:
-                pluginBinSandboxExecutionContract?.workingDirectory ||
+                executionPlugin.sandboxExecution?.workingDirectory ||
                 brokerExecOpts.cwd,
               shell: false,
               windowsHide: true,
@@ -5601,6 +6520,15 @@ async function executeToolInner(
               : {}),
             stderr: (err.stderr || "").substring(0, 2000),
             exitCode: err.status,
+            ...(typeof err.code === "string" && err.code
+              ? {
+                  policy: {
+                    decision: "deny",
+                    via: "dispatch-revalidation",
+                    code: err.code,
+                  },
+                }
+              : {}),
             ...shellMeta,
             ...pluginBinResult,
             shellCommandPolicy: shellPolicy,
@@ -5724,8 +6652,18 @@ async function executeToolInner(
         approvalGate &&
         typeof approvalGate.hasConfirmer === "function" &&
         !approvalGate.hasConfirmer();
+      // A durable remote-approval consumer is an explicit fail-closed mode.
+      // run_code does not yet carry an exact lease tuple, so it must still
+      // consult the remote confirmer in headless sessions; that confirmer
+      // returns lease-unavailable and no code is persisted or launched.
+      const durableAuthorizationGate =
+        approvalGate &&
+        typeof approvalGate.hasAuthorizationConsumer === "function" &&
+        approvalGate.hasAuthorizationConsumer() === true;
       if (
-        (interactiveApproval || policyGateNoConfirmer) &&
+        (interactiveApproval ||
+          policyGateNoConfirmer ||
+          durableAuthorizationGate) &&
         approvalGate &&
         !ruleAllowed &&
         typeof approvalGate.decide === "function"
@@ -5736,7 +6674,7 @@ async function executeToolInner(
           sessionId,
           riskLevel: APPROVAL_RISK.HIGH,
           tool: "run_code",
-          args: { language: args.language },
+          args: runCodeApprovalDescriptor(args, cwd),
         });
         if (gate.decision !== APPROVAL_DECISION.ALLOW) {
           // Actionable denial (matches run_shell, Claude-Code 2.1.193): tell the
@@ -5753,6 +6691,23 @@ async function executeToolInner(
             },
           });
         }
+        if (gate.authorization) {
+          return attachDescriptor({
+            error:
+              "[ApprovalGate] run_code received a durable authorization, but this tool does not yet implement an exact one-shot consume tuple. No code was launched.",
+            approval: {
+              decision: APPROVAL_DECISION.DENY,
+              via: "authorization-consume-unsupported",
+              riskLevel: "high",
+              policy: gate.policy,
+            },
+            policy: {
+              decision: "deny",
+              via: "authorization-consume-unsupported",
+              code: "CC_RUN_CODE_AUTHORIZATION_CONSUME_UNSUPPORTED",
+            },
+          });
+        }
       }
       return attachDescriptor(await _executeRunCode(args, cwd));
     }
@@ -5766,6 +6721,10 @@ async function executeToolInner(
           interaction,
           sessionId,
           llmOptions,
+          workflowEffectId,
+          workflowChildEffectId,
+          workflowChildSequence,
+          workflowEffectProtocol,
           subAgentDepth,
           subAgentBudget,
           sessionBudget,
@@ -6699,6 +7658,9 @@ async function executeToolInner(
             ? event
             : {
                 ...event,
+                ...(["model", "semantic-compaction"].includes(event?.source)
+                  ? { workflowRequestSource: event.source }
+                  : {}),
                 source:
                   event?.source === "semantic-compaction"
                     ? "semantic-compaction"
@@ -6774,6 +7736,9 @@ async function executeToolInner(
             toolAdmission,
             cwd,
             llmOptions: skillLlmOptions,
+            ...(strictUsageTelemetry === true && workflowChildEffectId
+              ? { workflowEffectId: workflowChildEffectId }
+              : {}),
             ...(sessionBudget ? { sessionBudget } : {}),
             ...(permissionRules ? { permissionRules } : {}),
             ...(hostManagedToolPolicy
@@ -6864,7 +7829,12 @@ async function executeToolInner(
             toolsUsed: result.toolsUsed,
           });
         } catch (err) {
-          if (err?.runtimeLedgerPersistence === true) throw err;
+          if (
+            err?.runtimeLedgerPersistence === true ||
+            err?.workflowEffectOutcomeUnknown === true
+          ) {
+            throw err;
+          }
           if (
             signal?.aborted ||
             skillExecutionSignal?.aborted ||
@@ -7088,6 +8058,14 @@ async function executeToolInner(
             ledgerTicket = await ledger.begin({
               sessionId,
               turnId,
+              ...(workflowEffectId
+                ? {
+                    workflowEffectId,
+                    workflowChildEffectId,
+                    workflowChildSequence,
+                    workflowEffectProtocol,
+                  }
+                : {}),
               toolName: localToolExecutor.toolName,
               serverName: localToolExecutor.serverName,
               input: mcpWireInput,
@@ -7161,12 +8139,20 @@ async function executeToolInner(
               localToolExecutor.toolName,
               mcpWireInput,
             ];
-            if (signal || mcpDispatchAdmission) {
+            if (signal || mcpDispatchAdmission || workflowEffectId) {
               callArguments.push({
                 ...(signal ? { signal } : {}),
                 ...(mcpDispatchAdmission
                   ? { dispatchAdmission: mcpDispatchAdmission }
                   : {}),
+                ...(workflowEffectId
+                  ? {
+                      workflowEffectId,
+                      workflowChildEffectId,
+                      workflowChildSequence,
+                      workflowEffectProtocol,
+                    }
+                  : {}),
               });
             }
             pendingResult = Reflect.apply(
@@ -7295,8 +8281,9 @@ async function executeToolInner(
             );
           }
 
+          let settledLedgerRecord;
           try {
-            await ledgerTicket.settle(
+            settledLedgerRecord = await ledgerTicket.settle(
               protocolError
                 ? {
                     status: "failed",
@@ -7318,11 +8305,26 @@ async function executeToolInner(
           }
 
           const mcpLedgerId = safeMcpProperty(ledgerTicket, "ledgerId") || null;
+          const mcpLedgerPrewritePersisted =
+            safeMcpProperty(ledgerTicket, "prewritePersisted") === true;
+          const mcpLedgerSettlementPersisted =
+            safeMcpProperty(settledLedgerRecord, "settlementPersistence") ===
+            "persisted";
           try {
             if (result && typeof result === "object") {
-              return attachDescriptor({ ...result, mcpLedgerId });
+              return attachDescriptor({
+                ...result,
+                mcpLedgerId,
+                mcpLedgerPrewritePersisted,
+                mcpLedgerSettlementPersisted,
+              });
             }
-            return attachDescriptor({ result, mcpLedgerId });
+            return attachDescriptor({
+              result,
+              mcpLedgerId,
+              mcpLedgerPrewritePersisted,
+              mcpLedgerSettlementPersisted,
+            });
           } catch (projectionError) {
             return attachDescriptor({
               error:
@@ -7349,7 +8351,18 @@ async function executeToolInner(
         interaction &&
         typeof interaction.requestHostTool === "function"
       ) {
-        const hostedResult = await interaction.requestHostTool(name, args);
+        const hostedResult = workflowEffectId
+          ? await interaction.requestHostTool(
+              name,
+              args,
+              Object.freeze({
+                workflowEffectId,
+                workflowChildEffectId,
+                workflowChildSequence,
+                workflowEffectProtocol,
+              }),
+            )
+          : await interaction.requestHostTool(name, args);
         if (hostedResult?.success === false) {
           return attachDescriptor({
             error:
@@ -8012,7 +9025,12 @@ function _backgroundSubAgentResultText(entry) {
 
 function _throwBackgroundSubAgentUsageFailure(entry) {
   const error = entry?.outcome?.fatalError;
-  if (error?.runtimeLedgerPersistence === true) throw error;
+  if (
+    error?.runtimeLedgerPersistence === true ||
+    error?.workflowEffectOutcomeUnknown === true
+  ) {
+    throw error;
+  }
 }
 
 function _throwSettledBackgroundUsageFailure(map) {
@@ -8567,6 +9585,9 @@ async function _executeSpawnSubAgent(args, ctx) {
       ? u
       : {
           ...u,
+          ...(["model", "semantic-compaction"].includes(u?.source)
+            ? { workflowRequestSource: u.source }
+            : {}),
           source:
             u?.source === "semantic-compaction"
               ? "semantic-compaction"
@@ -8716,6 +9737,9 @@ async function _executeSpawnSubAgent(args, ctx) {
     cwd: ctx.cwd,
     profile: profile || null,
     llmOptions: subLlmOptions,
+    ...(ctx.strictUsageTelemetry === true && ctx.workflowChildEffectId
+      ? { workflowEffectId: ctx.workflowChildEffectId }
+      : {}),
     depth: currentDepth + 1, // nested spawns see their own level
     // Same shared counter object so the child's own spawns draw from the run's
     // single total-sub-agent pool (breadth cap spans the whole tree).
@@ -8917,7 +9941,8 @@ async function _executeSpawnSubAgent(args, ctx) {
           return {
             result: subCtx.result,
             error: err.message,
-            ...(err?.runtimeLedgerPersistence === true
+            ...(err?.runtimeLedgerPersistence === true ||
+            err?.workflowEffectOutcomeUnknown === true
               ? { fatalError: err }
               : {}),
           };
@@ -9050,7 +10075,12 @@ async function _executeSpawnSubAgent(args, ctx) {
       completedAt: subCtx.completedAt,
     });
 
-    if (err?.runtimeLedgerPersistence === true) throw err;
+    if (
+      err?.runtimeLedgerPersistence === true ||
+      err?.workflowEffectOutcomeUnknown === true
+    ) {
+      throw err;
+    }
 
     return {
       error: `Sub-agent failed: ${err.message}`,
@@ -9130,6 +10160,72 @@ function _hasCompleteProviderUsage(usage) {
   );
 }
 
+const PROVIDER_REQUEST_ID_RE = /^[\x21-\x7e]{1,512}$/;
+const PROVIDER_RECEIPT_ID_RE = /^[A-Za-z0-9._:-]{1,256}$/;
+
+function _normalizeProviderRequestId(value) {
+  if (value == null) return null;
+  if (typeof value !== "string" || !PROVIDER_REQUEST_ID_RE.test(value)) {
+    throw new TypeError(
+      "providerRequestId must be 1-512 printable ASCII characters",
+    );
+  }
+  return value;
+}
+
+function _physicalProviderRequestId(logicalRequestId, attempt) {
+  if (!logicalRequestId) return null;
+  const retry = Number(attempt);
+  if (!Number.isSafeInteger(retry) || retry <= 0) return logicalRequestId;
+  const suffix = `-r${retry}`;
+  return `${logicalRequestId.slice(0, 512 - suffix.length)}${suffix}`;
+}
+
+function _providerReceiptId(value) {
+  return typeof value === "string" && PROVIDER_RECEIPT_ID_RE.test(value)
+    ? value
+    : null;
+}
+
+function _isOfficialOpenAIEndpoint(provider, baseUrl) {
+  if (provider !== "openai") return false;
+  try {
+    const parsed = new URL(String(baseUrl));
+    return (
+      parsed.protocol === "https:" &&
+      parsed.hostname.toLowerCase() === "api.openai.com" &&
+      !parsed.port &&
+      !parsed.username &&
+      !parsed.password
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Capture only provider-returned identifiers. X-Client-Request-Id is a
+ * trace/correlation header, not an idempotency guarantee, so a locally sent
+ * client id alone is deliberately not called a receipt.
+ */
+function _openAIProviderRequestReceipt(response, data, clientRequestId) {
+  if (!clientRequestId) return null;
+  const requestId = _providerReceiptId(
+    response?.headers?.get?.("x-request-id"),
+  );
+  const responseId = _providerReceiptId(data?.id);
+  if (!requestId && !responseId) return null;
+  return Object.freeze({
+    protocol: "cc-provider-request-receipt/v1",
+    provider: "openai",
+    clientRequestId,
+    requestId,
+    responseId,
+    requestIdentitySemantics: "trace-only",
+    independentlyReadable: false,
+  });
+}
+
 /**
  * Send a chat completion request with tool definitions.
  * Supports 8 providers: ollama, anthropic, openai, deepseek, dashscope, gemini, mistral, volcengine
@@ -9148,6 +10244,10 @@ export async function chatWithTools(rawMessages, options) {
     signal,
   } = options;
 
+  const providerRequestId = _normalizeProviderRequestId(
+    options.providerRequestId,
+  );
+
   const tools = getEffectiveToolDefinitions(options);
 
   const lastUserMsg = [...rawMessages].reverse().find((m) => m.role === "user");
@@ -9193,6 +10293,7 @@ export async function chatWithTools(rawMessages, options) {
           ),
         {
           signal,
+          retries: options.workflowEffectId ? 0 : undefined,
           strictRetryObserver: options.strictUsageTelemetry === true,
           ...(typeof options.onStreamRetry === "function"
             ? {
@@ -9342,6 +10443,7 @@ export async function chatWithTools(rawMessages, options) {
           ),
         {
           signal,
+          retries: options.workflowEffectId ? 0 : undefined,
           strictRetryObserver: options.strictUsageTelemetry === true,
           ...(typeof options.onStreamRetry === "function"
             ? {
@@ -9434,6 +10536,10 @@ export async function chatWithTools(rawMessages, options) {
       `Unsupported provider: ${provider}. Supported: ollama, anthropic, openai, deepseek, dashscope, mistral, gemini, volcengine`,
     );
   }
+  const supportsOpenAIRequestIdentity = _isOfficialOpenAIEndpoint(
+    provider,
+    url,
+  );
 
   const envKey = providerApiKeyEnvs[provider] || "OPENAI_API_KEY";
   const key = apiKey || process.env[envKey];
@@ -9445,7 +10551,7 @@ export async function chatWithTools(rawMessages, options) {
     dashscope: "qwen-turbo",
     mistral: "mistral-large-latest",
     gemini: "gemini-2.0-flash",
-    volcengine: "doubao-seed-2-1-pro-260628",
+    volcengine: "deepseek-v4-flash-260425",
   };
 
   // Real token streaming (--include-partial-messages) for every OpenAI-compatible
@@ -9454,7 +10560,7 @@ export async function chatWithTools(rawMessages, options) {
   // delta-fragmented tool_calls into the standard {message, usage} shape.
   if (typeof options.onToken === "function") {
     return await _retryStreamingChat(
-      () =>
+      (attempt = 0) =>
         _chatOpenAIStreaming(
           `${url}/chat/completions`,
           {
@@ -9474,9 +10580,13 @@ export async function chatWithTools(rawMessages, options) {
           options.onStall,
           options.streamStallMs,
           options.streamStallTimeoutMs,
+          supportsOpenAIRequestIdentity
+            ? _physicalProviderRequestId(providerRequestId, attempt)
+            : null,
         ),
       {
         signal,
+        retries: options.workflowEffectId ? 0 : undefined,
         strictRetryObserver: options.strictUsageTelemetry === true,
         ...(typeof options.onStreamRetry === "function"
           ? {
@@ -9497,6 +10607,9 @@ export async function chatWithTools(rawMessages, options) {
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${key}`,
+      ...(supportsOpenAIRequestIdentity && providerRequestId
+        ? { "X-Client-Request-Id": providerRequestId }
+        : {}),
     },
     signal,
     body: JSON.stringify({
@@ -9519,6 +10632,10 @@ export async function chatWithTools(rawMessages, options) {
   }
   const choice = data.choices[0];
   const out = { message: choice.message };
+  const providerReceipt = supportsOpenAIRequestIdentity
+    ? _openAIProviderRequestReceipt(response, data, providerRequestId)
+    : null;
+  if (providerReceipt) out.providerReceipt = providerReceipt;
   if (_hasCompleteProviderUsage(data.usage)) {
     // OpenAI/DeepSeek/volcengine report cached prompt tokens AS PART of
     // prompt_tokens — split them out so cost prices the cached prefix at the
@@ -9761,7 +10878,7 @@ export async function _retryStreamingChat(streamFn, opts = {}) {
   for (;;) {
     const attemptStartedAt = now();
     try {
-      return await streamFn();
+      return await streamFn(attempt);
     } catch (err) {
       if (attempt >= retries || !_isRetryableStreamError(err, signal))
         throw err;
@@ -10241,6 +11358,7 @@ function _openaiCachedTokens(usage) {
 
 function _openaiInitState() {
   return {
+    responseId: null,
     text: "",
     tools: [],
     inputTokens: null,
@@ -10261,6 +11379,7 @@ function _openaiReduceLine(state, raw, onToken) {
   } catch {
     return state;
   }
+  if (!state.responseId) state.responseId = _providerReceiptId(obj.id);
   const delta = obj.choices?.[0]?.delta;
   if (delta?.content) {
     state.text += delta.content;
@@ -10347,12 +11466,16 @@ async function _chatOpenAIStreaming(
   onStall,
   stallMs,
   stallTimeoutMs,
+  providerRequestId = null,
 ) {
   const response = await fetch(apiUrl, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${apiKey}`,
+      ...(providerRequestId
+        ? { "X-Client-Request-Id": providerRequestId }
+        : {}),
     },
     signal,
     body: JSON.stringify(body),
@@ -10386,9 +11509,23 @@ async function _chatOpenAIStreaming(
   } catch (err) {
     if (_streamErrorDisposition(err, signal, state.text) === "rethrow")
       throw err;
-    return _finalizeTruncatedStream(_openaiFinalize, state);
-  }
-  return _openaiFinalize(state);
+    const out = _finalizeTruncatedStream(_openaiFinalize, state);
+    const providerReceipt = _openAIProviderRequestReceipt(
+      response,
+      { id: state.responseId },
+      providerRequestId,
+    );
+    if (providerReceipt) out.providerReceipt = providerReceipt;
+    return out;
+  }
+  const out = _openaiFinalize(state);
+  const providerReceipt = _openAIProviderRequestReceipt(
+    response,
+    { id: state.responseId },
+    providerRequestId,
+  );
+  if (providerReceipt) out.providerReceipt = providerReceipt;
+  return out;
 }
 
 /**
@@ -10685,6 +11822,7 @@ function _managedCheckpointUncoveredWriterReason(toolContext) {
  *   { type: "tool-executing", tool, args }
  *   { type: "tool-result", tool, result, error }
  *   { type: "model-usage-started", callId, provider, model, source }
+ *   { type: "provider-request-receipt", source, workflowEffectId, clientRequestId, requestId, responseId }
  *   { type: "token-usage", callId, provider, model, usage, source? }
  *   { type: "model-usage-unknown", callId, provider, model, source, code }
  *   { type: "response-complete", content }
@@ -10708,6 +11846,154 @@ function _newModelUsageCallId(source = "model") {
   return `${prefix}-${randomUUID()}`;
 }
 
+const WORKFLOW_EFFECT_ID_RE = /^sha256:[a-f0-9]{64}$/;
+const WORKFLOW_CHILD_EFFECT_PROTOCOL = "cc-workflow-child-effect/v1";
+const WORKFLOW_TOOL_CALL_ID_RE = /^[\x21-\x7e]{1,512}$/;
+
+function _normalizeWorkflowEffectId(value) {
+  if (value == null) return null;
+  if (typeof value !== "string" || !WORKFLOW_EFFECT_ID_RE.test(value)) {
+    throw new TypeError("workflowEffectId must be a canonical sha256 identity");
+  }
+  return value;
+}
+
+function _workflowProviderRequestId(workflowEffectId, source, sequence) {
+  if (!workflowEffectId) return null;
+  return `ccwf_${createHash("sha256")
+    .update(
+      `${workflowEffectId}\0${String(source || "model")}\0${String(sequence)}`,
+      "utf8",
+    )
+    .digest("hex")}`;
+}
+
+function _workflowToolEffectBinding(
+  workflowEffectId,
+  sequence,
+  toolCallId,
+  toolName,
+) {
+  if (!workflowEffectId) return null;
+  if (
+    !Number.isSafeInteger(sequence) ||
+    sequence < 1 ||
+    typeof toolCallId !== "string" ||
+    !WORKFLOW_TOOL_CALL_ID_RE.test(toolCallId) ||
+    typeof toolName !== "string" ||
+    !toolName
+  ) {
+    const error = new TypeError(
+      "workflow-bound tool call identity is malformed",
+    );
+    error.code = "CC_WORKFLOW_CHILD_EFFECT_IDENTITY_INVALID";
+    throw error;
+  }
+  const childEffectId = `sha256:${createHash("sha256")
+    .update(
+      `${workflowEffectId}\0tool\0${String(sequence)}\0${toolCallId}\0${toolName}`,
+      "utf8",
+    )
+    .digest("hex")}`;
+  return Object.freeze({
+    workflowEffectProtocol: WORKFLOW_CHILD_EFFECT_PROTOCOL,
+    workflowEffectId,
+    workflowChildEffectId: childEffectId,
+    workflowChildSequence: sequence,
+  });
+}
+
+function _workflowNestedToolOutcomeUnknown(binding, toolName, result) {
+  if (!binding || safeMcpProperty(result, "outcomeUnknown") !== true) {
+    return null;
+  }
+  const error = new Error(
+    `Workflow-bound nested tool ${toolName} has an unknown outcome and requires reconciliation`,
+  );
+  error.code = "CC_WORKFLOW_NESTED_TOOL_OUTCOME_UNKNOWN";
+  error.workflowEffectOutcomeUnknown = true;
+  error.workflowEffectId = binding.workflowEffectId;
+  error.workflowChildEffectId = binding.workflowChildEffectId;
+  return error;
+}
+
+function _workflowCompactionOutcomeUnknown(
+  cause,
+  code = "CC_WORKFLOW_COMPACTION_PROVIDER_OUTCOME_UNKNOWN",
+  message = "Workflow-bound semantic compaction provider outcome is unknown",
+) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = code;
+  error.workflowEffectOutcomeUnknown = true;
+  error.compactionFailureReported = false;
+  return error;
+}
+
+function _markWorkflowCompactionFailureReported(error) {
+  if (error?.workflowEffectOutcomeUnknown === true) {
+    error.compactionFailureReported = true;
+  }
+  return error;
+}
+
+function _snapshotProviderRequestReceipt(
+  value,
+  expectedClientRequestId,
+  expectedProvider,
+) {
+  if (value == null) return null;
+  if (isProxy(value)) {
+    throw new TypeError("provider request receipt must not be a Proxy");
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const expectedFields = [
+    "clientRequestId",
+    "independentlyReadable",
+    "protocol",
+    "provider",
+    "requestId",
+    "requestIdentitySemantics",
+    "responseId",
+  ];
+  const fields = Object.keys(descriptors).sort();
+  const hasOnlyDataFields =
+    fields.length === expectedFields.length &&
+    fields.every(
+      (field, index) =>
+        field === expectedFields[index] &&
+        Object.hasOwn(descriptors[field], "value") &&
+        descriptors[field].enumerable === true,
+    );
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    !hasOnlyDataFields ||
+    descriptors.protocol.value !== "cc-provider-request-receipt/v1" ||
+    !/^[a-z0-9][a-z0-9._-]{0,63}$/.test(descriptors.provider.value || "") ||
+    descriptors.provider.value !== expectedProvider ||
+    descriptors.clientRequestId.value !== expectedClientRequestId ||
+    descriptors.requestIdentitySemantics.value !== "trace-only" ||
+    descriptors.independentlyReadable.value !== false
+  ) {
+    throw new TypeError("provider request receipt is malformed");
+  }
+  const requestId = _providerReceiptId(descriptors.requestId.value);
+  const responseId = _providerReceiptId(descriptors.responseId.value);
+  if (!requestId && !responseId) {
+    throw new TypeError("provider request receipt has no provider identifier");
+  }
+  return Object.freeze({
+    protocol: "cc-provider-request-receipt/v1",
+    provider: descriptors.provider.value,
+    clientRequestId: expectedClientRequestId,
+    requestId,
+    responseId,
+    requestIdentitySemantics: "trace-only",
+    independentlyReadable: false,
+  });
+}
+
 function _runtimeUsageBoundaryFailure(error, code, fallbackMessage) {
   const failure =
     error && (typeof error === "object" || typeof error === "function")
@@ -10877,7 +12163,7 @@ function _assertStrictUsageObserver(observer, phase) {
 function _autoCompactionUsageState(options) {
   let state = _autoCompactionUsageStates.get(options);
   if (!state) {
-    state = { calls: [] };
+    state = { calls: [], callSequence: null };
     _autoCompactionUsageStates.set(options, state);
   }
   return state;
@@ -10901,27 +12187,59 @@ function _instrumentAutoCompactorUsage(compactor, options) {
   const original = installed?.original || compactor.llmQuery;
   const state = _autoCompactionUsageState(options);
   const wrapper = async function instrumentedCompactionQuery(...args) {
+    const workflowEffectId = _normalizeWorkflowEffectId(
+      options.workflowEffectId,
+    );
+    const callSequence =
+      Number.isSafeInteger(state.callSequence) && state.callSequence > 0
+        ? state.callSequence
+        : null;
+    if (workflowEffectId && callSequence == null) {
+      throw _runtimeUsageBoundaryFailure(
+        null,
+        "CC_COMPACTION_REQUEST_SEQUENCE_REQUIRED",
+        "Workflow-bound semantic compaction requires a stable call sequence",
+      );
+    }
+    const providerRequestId = _workflowProviderRequestId(
+      workflowEffectId,
+      "semantic-compaction",
+      callSequence,
+    );
     const call = {
       callId: _newModelUsageCallId("semantic-compaction"),
-      provider: options.provider || null,
-      model: options.model || null,
+      provider: options.provider || "ollama",
+      model: options.model || "unknown",
       source: "semantic-compaction",
+      workflowEffectId,
+      callSequence,
+      providerRequestId,
+      providerReceipt: null,
       observerError: null,
       observerFailed: false,
       boundaryNotified: false,
     };
     state.calls.push(call);
+    const boundaryEvent = {
+      type: "model-usage-started",
+      callId: call.callId,
+      provider: call.provider,
+      model: call.model,
+      source: call.source,
+      ...(providerRequestId
+        ? {
+            workflowEffectId,
+            callSequence,
+            providerRequestId,
+            requestIdentitySemantics: "trace-only",
+          }
+        : {}),
+    };
     try {
       if (typeof options.onUsageBoundary === "function") {
         // Synchronous and before `original`: a host can durably append the
         // start row, and any append failure prevents provider spend.
-        const observation = options.onUsageBoundary({
-          type: "model-usage-started",
-          callId: call.callId,
-          provider: call.provider,
-          model: call.model,
-          source: call.source,
-        });
+        const observation = options.onUsageBoundary(boundaryEvent);
         if (observation && typeof observation.then === "function") {
           void Promise.resolve(observation).catch(() => {});
           const error = new Error(
@@ -10932,13 +12250,54 @@ function _instrumentAutoCompactorUsage(compactor, options) {
         }
         call.boundaryNotified = true;
       }
+      if (
+        providerRequestId &&
+        typeof options.onProviderRequestBoundary === "function"
+      ) {
+        const observation = options.onProviderRequestBoundary(boundaryEvent);
+        if (observation && typeof observation.then === "function") {
+          void Promise.resolve(observation).catch(() => {});
+          throw _runtimeUsageBoundaryFailure(
+            null,
+            "CC_PROVIDER_REQUEST_BOUNDARY_ASYNC",
+            "Provider request boundary observer must be synchronous",
+          );
+        }
+      }
     } catch (error) {
       call.observerError = error;
       call.observerFailed = true;
       throw error;
     }
 
-    return await original.apply(this, args);
+    const requestBinding = providerRequestId
+      ? Object.freeze({
+          workflowEffectId,
+          callSequence,
+          source: "semantic-compaction",
+          providerRequestId,
+          requestIdentitySemantics: "trace-only",
+        })
+      : null;
+    try {
+      const result = await original.apply(
+        this,
+        requestBinding ? [...args, requestBinding] : args,
+      );
+      call.providerReceipt = providerRequestId
+        ? _snapshotProviderRequestReceipt(
+            result?.providerReceipt,
+            providerRequestId,
+            call.provider,
+          )
+        : null;
+      return result;
+    } catch (error) {
+      if (workflowEffectId) {
+        throw _workflowCompactionOutcomeUnknown(error);
+      }
+      throw error;
+    }
   };
 
   try {
@@ -10992,7 +12351,7 @@ async function _getAutoCompactor(options) {
           ? options.compactionLlmQuery
           : options.chatFn
             ? null
-            : async (prompt) => {
+            : async (prompt, requestBinding = null) => {
                 const maxOutputTokens = Math.min(
                   4096,
                   Math.max(
@@ -11011,14 +12370,17 @@ async function _getAutoCompactor(options) {
                     onToken: undefined,
                     onStall: undefined,
                     onStreamRetry: undefined,
+                    providerRequestId:
+                      requestBinding?.providerRequestId || undefined,
                     maxOutputTokens,
                   },
                 );
                 return {
                   summary: response?.message?.content || "",
                   usage: response?.usage || null,
-                  provider: options.provider || null,
-                  model: options.model || null,
+                  provider: options.provider || "ollama",
+                  model: options.model || "unknown",
+                  providerReceipt: response?.providerReceipt || null,
                 };
               };
       compressor = new PromptCompressor({
@@ -11258,6 +12620,7 @@ export async function* agentLoop(messages, options) {
     await import("../lib/iteration-budget.js");
   const budget = options.iterationBudget || new IterationBudget();
   const signal = options.signal || null;
+  const workflowEffectId = _normalizeWorkflowEffectId(options.workflowEffectId);
   // Optional OpenTelemetry recorder (TelemetryRecorder). When present, the loop
   // emits model/tool/retry spans + a per-run counter; when absent, zero cost.
   const recorder = options.recorder || null;
@@ -11268,6 +12631,7 @@ export async function* agentLoop(messages, options) {
     options.runId ||
     `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   let automaticCompactionSettlementBlocked = false;
+  let workflowChildEffectSequence = 0;
 
   const fileMutationScope = normalizeExactFileMutationScope(
     options.fileMutationScope,
@@ -11367,6 +12731,7 @@ export async function* agentLoop(messages, options) {
     mcpDispatchAdmission: hermeticExecution
       ? null
       : options.mcpDispatchAdmission || null,
+    workflowEffectId,
     // A loop-local identity prevents one session's lazy instruction commits
     // from suppressing first-access delivery in another session at the same
     // cwd. Hosts may inject a stable identity across resumed turns.
@@ -11560,10 +12925,13 @@ export async function* agentLoop(messages, options) {
   // attempt inside one logical `llmCall`, where this generator cannot durably
   // bracket each transport attempt. Strict call-ledger sessions therefore
   // disable that recovery path and surface the configured provider's failure
-  // as unknown; legacy sessions keep the existing self-healing behavior.
+  // as unknown. A workflow-bound request does the same: a hidden fallback
+  // would be a second physical provider attempt under one durable effect.
+  // Legacy sessions keep the existing self-healing behavior.
   if (
     options.runnableProviderFallback !== false &&
-    options.strictUsageTelemetry !== true
+    options.strictUsageTelemetry !== true &&
+    workflowEffectId == null
   ) {
     const { makeRunnableProviderFallback } =
       await import("../lib/runnable-provider.js");
@@ -11707,6 +13075,7 @@ export async function* agentLoop(messages, options) {
         if (compactor && compactor.shouldAutoCompact(messages)) {
           compactionUsageState = _autoCompactionUsageState(options);
           compactionUsageState.calls = [];
+          compactionUsageState.callSequence = budget.consumed;
           // This is the canonical pre-provider authority snapshot. A local
           // micro-compact may change the working input, but the durable CAS must
           // still compare against the transcript state that existed before any
@@ -11803,6 +13172,16 @@ export async function* agentLoop(messages, options) {
           }
           compactionUsageCall = compactionUsageState.calls.at(-1) || null;
           const compactionUsage = _compactionTokenUsage(stats);
+          if (compactionUsageCall?.providerReceipt) {
+            yield {
+              type: "provider-request-receipt",
+              callId: compactionUsageCall.callId,
+              workflowEffectId,
+              callSequence: compactionUsageCall.callSequence,
+              source: "semantic-compaction",
+              ...compactionUsageCall.providerReceipt,
+            };
+          }
           if (stats.degraded === true) {
             const usageOutcomeUnknown = stats.summaryUsageUnknown === true;
             const projectedStats = usageOutcomeUnknown
@@ -11869,6 +13248,15 @@ export async function* agentLoop(messages, options) {
               backgroundSubAgents,
               backgroundUsageFailureState,
             );
+            if (workflowEffectId) {
+              throw _markWorkflowCompactionFailureReported(
+                _workflowCompactionOutcomeUnknown(
+                  null,
+                  "CC_WORKFLOW_COMPACTION_USAGE_UNKNOWN",
+                  "Workflow-bound semantic compaction usage is unknown",
+                ),
+              );
+            }
             return;
           }
           if (
@@ -11922,6 +13310,15 @@ export async function* agentLoop(messages, options) {
                 backgroundSubAgents,
                 backgroundUsageFailureState,
               );
+              if (workflowEffectId) {
+                throw _markWorkflowCompactionFailureReported(
+                  _workflowCompactionOutcomeUnknown(
+                    error,
+                    "CC_WORKFLOW_COMPACTION_SETTLEMENT_UNKNOWN",
+                    "Workflow-bound semantic compaction settlement is unknown",
+                  ),
+                );
+              }
               return;
             }
             if (!hermeticExecution) {
@@ -11969,6 +13366,12 @@ export async function* agentLoop(messages, options) {
       } catch (_e) {
         if (isAbortError(_e) || signal?.aborted) throw _e;
         if (_e?.runtimeLedgerPersistence === true) throw _e;
+        if (
+          _e?.workflowEffectOutcomeUnknown === true &&
+          _e?.compactionFailureReported === true
+        ) {
+          throw _e;
+        }
         if (compactionObserverFailure === _e) throw _e;
         const observerFailure = compactionUsageState?.calls?.find(
           (call) => call.observerFailed && call.observerError === _e,
@@ -11995,6 +13398,13 @@ export async function* agentLoop(messages, options) {
             backgroundSubAgents,
             backgroundUsageFailureState,
           );
+          if (workflowEffectId) {
+            throw _markWorkflowCompactionFailureReported(
+              _e?.workflowEffectOutcomeUnknown === true
+                ? _e
+                : _workflowCompactionOutcomeUnknown(_e),
+            );
+          }
           return;
         }
         yield {
@@ -12101,12 +13511,28 @@ export async function* agentLoop(messages, options) {
     throwIfAborted(signal);
     _throwBackgroundUsageFailureState(backgroundUsageFailureState);
     _throwSettledBackgroundUsageFailure(backgroundSubAgents);
+    const providerRequestId = _workflowProviderRequestId(
+      workflowEffectId,
+      "model",
+      budget.consumed,
+    );
+    const providerCallOptions = providerRequestId
+      ? { ...effectiveToolOptions, providerRequestId }
+      : effectiveToolOptions;
     const modelUsageCall = {
       type: "model-usage-started",
       callId: _newModelUsageCallId("model"),
       provider: options.provider || "ollama",
       model: options.model || "unknown",
       source: "model",
+      ...(providerRequestId
+        ? {
+            workflowEffectId,
+            callSequence: budget.consumed,
+            providerRequestId,
+            requestIdentitySemantics: "trace-only",
+          }
+        : {}),
     };
     // The consumer receives this boundary before `.next()` resumes into the
     // provider call, so a durable append failure can prevent spend.
@@ -12132,6 +13558,7 @@ export async function* agentLoop(messages, options) {
     }
 
     let result;
+    let providerReceipt = null;
     try {
       result = await _withSpan(
         recorder,
@@ -12142,7 +13569,7 @@ export async function* agentLoop(messages, options) {
           "agent.iteration": budget.consumed,
           ...(modelIdAttrs || {}),
         },
-        () => llmCall(callMessages, effectiveToolOptions),
+        () => llmCall(callMessages, providerCallOptions),
         (span, r) => {
           const t = _usageTokens(r?.usage);
           if (t) {
@@ -12183,6 +13610,13 @@ export async function* agentLoop(messages, options) {
         },
         "model_error",
       );
+      providerReceipt = providerRequestId
+        ? _snapshotProviderRequestReceipt(
+            result?.providerReceipt,
+            providerRequestId,
+            modelUsageCall.provider,
+          )
+        : null;
     } catch (error) {
       // Never retain provider error text in the usage ledger. Pause on a fixed
       // unknown settlement, then rethrow only after the consumer resumes.
@@ -12203,6 +13637,20 @@ export async function* agentLoop(messages, options) {
     if (recorder) recorder.counter("agent.model.calls", 1);
     const msg = result?.message;
 
+    if (providerReceipt) {
+      // Yield the provider-returned identifiers before billable usage. A host
+      // that stops after a cost boundary still retains the exact request/effect
+      // binding. This is trace evidence only, never an exactly-once assertion.
+      yield {
+        type: "provider-request-receipt",
+        callId: modelUsageCall.callId,
+        workflowEffectId,
+        callSequence: budget.consumed,
+        source: modelUsageCall.source,
+        ...providerReceipt,
+      };
+    }
+
     // Close the already-persisted call boundary before honoring an abort that
     // raced with a successful provider response. Once the transport returned,
     // dropping this settlement would strand a durable `started` row forever.
@@ -12428,7 +13876,13 @@ export async function* agentLoop(messages, options) {
         } catch {
           toolArgs = {};
         }
-        return { call, toolArgs };
+        const workflowBinding = _workflowToolEffectBinding(
+          workflowEffectId,
+          workflowEffectId ? (workflowChildEffectSequence += 1) : 0,
+          call.id,
+          call.function.name,
+        );
+        return { call, toolArgs, workflowBinding };
       });
       // Yield every start boundary before dispatch. Async-generator consumers
       // persist each boundary before asking for the next item, so by the time
@@ -12437,20 +13891,21 @@ export async function* agentLoop(messages, options) {
       try {
         throwIfAborted(signal);
         _throwBackgroundUsageFailureState(backgroundUsageFailureState);
-        for (const { call, toolArgs } of prepared) {
+        for (const { call, toolArgs, workflowBinding } of prepared) {
           yield {
             type: "tool-executing",
             tool: call.function.name,
             args: toolArgs,
             tool_use_id: call.id,
             turn_id: `${runId}:t${budget.consumed}`,
+            ...(workflowBinding || {}),
           };
-          startedPrepared.push({ call, toolArgs });
+          startedPrepared.push({ call, toolArgs, workflowBinding });
           throwIfAborted(signal);
         }
         _throwBackgroundUsageFailureState(backgroundUsageFailureState);
       } catch (admissionFailure) {
-        for (const { call } of startedPrepared) {
+        for (const { call, workflowBinding } of startedPrepared) {
           yield {
             type: "tool-result",
             tool: call.function.name,
@@ -12458,6 +13913,7 @@ export async function* agentLoop(messages, options) {
             error: "tool execution cancelled before dispatch",
             tool_use_id: call.id,
             turn_id: `${runId}:t${budget.consumed}`,
+            ...(workflowBinding || {}),
           };
         }
         throw admissionFailure;
@@ -12465,18 +13921,30 @@ export async function* agentLoop(messages, options) {
       // Only after every start has been consumed do we kick every read off.
       // Settle each promise into {result,error} so an abort before its ordered
       // result is consumed can never surface an unhandled rejection.
-      const inflight = prepared.map(({ call, toolArgs }) => {
+      const inflight = prepared.map(({ call, toolArgs, workflowBinding }) => {
         const promise = executeTool(call.function.name, toolArgs, {
           ...toolContext,
           toolCallId: call.id,
           turnId: `${runId}:t${budget.consumed}`,
+          ...(workflowBinding || {}),
         }).then(
           (result) => ({ result, error: null }),
-          (err) => ({ result: { error: err.message }, error: err.message }),
+          (err) => ({
+            result: {
+              error: err.message,
+              ...(workflowBinding
+                ? {
+                    code: "CC_WORKFLOW_NESTED_TOOL_EXECUTION_THROWN",
+                    outcomeUnknown: true,
+                  }
+                : {}),
+            },
+            error: err.message,
+          }),
         );
-        return { call, toolArgs, promise };
+        return { call, toolArgs, workflowBinding, promise };
       });
-      for (const { call, toolArgs, promise } of inflight) {
+      for (const { call, toolArgs, workflowBinding, promise } of inflight) {
         throwIfAborted(signal);
         _throwBackgroundUsageFailureState(backgroundUsageFailureState);
         const { result: toolResult, error: toolError } = await promise;
@@ -12516,9 +13984,16 @@ export async function* agentLoop(messages, options) {
           error: toolError,
           tool_use_id: call.id,
           turn_id: `${runId}:t${budget.consumed}`,
+          ...(workflowBinding || {}),
           permission_decision_id: decision?.id || null,
           permission_decision: decision,
         };
+        const nestedOutcomeUnknown = _workflowNestedToolOutcomeUnknown(
+          workflowBinding,
+          call.function.name,
+          toolResult,
+        );
+        if (nestedOutcomeUnknown) throw nestedOutcomeUnknown;
         messages.push({
           role: "tool",
           content: toolContent,
@@ -12663,6 +14138,7 @@ export async function* agentLoop(messages, options) {
 
       let managedCheckpointHandle = null;
       let managedCheckpointPreparationError = null;
+      let workflowBinding = null;
       try {
         managedCheckpointHandle = beginManagedToolCheckpoint({
           enabled: toolContext.managedCheckpoint === true,
@@ -12716,12 +14192,19 @@ export async function* agentLoop(messages, options) {
         // event. Consumers use that event to bind hooks, telemetry and turns to
         // an actual invocation.
         if (!managedCheckpointPreparationError) {
+          workflowBinding = _workflowToolEffectBinding(
+            workflowEffectId,
+            workflowEffectId ? (workflowChildEffectSequence += 1) : 0,
+            call.id,
+            toolName,
+          );
           yield {
             type: "tool-executing",
             tool: toolName,
             args: toolArgs,
             tool_use_id: call.id,
             turn_id: `${runId}:t${budget.consumed}`,
+            ...(workflowBinding || {}),
           };
           // The event yield is a host persistence boundary. A detached child's
           // fatal usage write can settle while the consumer handles it; fence
@@ -12739,6 +14222,7 @@ export async function* agentLoop(messages, options) {
               error: "authoritative background usage persistence failure",
               tool_use_id: call.id,
               turn_id: `${runId}:t${budget.consumed}`,
+              ...(workflowBinding || {}),
             };
             throw backgroundFailure;
           }
@@ -12788,6 +14272,7 @@ export async function* agentLoop(messages, options) {
                   ...toolContext,
                   toolCallId: call.id,
                   turnId: `${runId}:t${budget.consumed}`,
+                  ...(workflowBinding || {}),
                 }),
               (span, r) => {
                 span.setAttribute(
@@ -12827,7 +14312,15 @@ export async function* agentLoop(messages, options) {
             );
           } catch (err) {
             if (err?.runtimeLedgerPersistence === true) throw err;
-            toolResult = { error: err.message };
+            toolResult = {
+              error: err.message,
+              ...(workflowBinding
+                ? {
+                    code: "CC_WORKFLOW_NESTED_TOOL_EXECUTION_THROWN",
+                    outcomeUnknown: true,
+                  }
+                : {}),
+            };
             toolError = err.message;
           }
         }
@@ -12931,10 +14424,18 @@ export async function* agentLoop(messages, options) {
           error: toolError,
           tool_use_id: call.id,
           turn_id: `${runId}:t${budget.consumed}`,
+          ...(workflowBinding || {}),
           permission_decision_id: decision?.id || null,
           permission_decision: decision,
         };
 
+        const nestedOutcomeUnknown = _workflowNestedToolOutcomeUnknown(
+          workflowBinding,
+          toolName,
+          toolResult,
+        );
+        if (nestedOutcomeUnknown) throw nestedOutcomeUnknown;
+
         messages.push({
           role: "tool",
           content: toolContent,