chainlesschain 0.162.189 → 0.162.193

package/src/runtime/agent-core.js

@@ -18,6 +18,7 @@ import fs from "fs";
 import path from "path";
 import broker from "../lib/process-execution-broker/index.js";
 import os from "os";
+import { isProxy } from "node:util/types";
 import sharedCodingAgentPolicy from "./coding-agent-policy.cjs";
 import sharedShellPolicy from "./coding-agent-shell-policy.cjs";
 import sharedPermissionRules from "../lib/permission-rules.cjs";
@@ -59,7 +60,6 @@ import {
 } from "../lib/idempotency.js";
 import { buildSearchCommand } from "../lib/search-command.js";
 import { discoverCommands } from "../lib/slash-commands.js";
-import { createSkillProcessBroker } from "../lib/skill-process-broker.js";
 import {
   isRetryableStreamError,
   STREAM_RETRY_BASE_MS,
@@ -70,10 +70,6 @@ import {
   replaceByHash,
   snippetAround,
 } from "../lib/hashline.js";
-import {
-  mountSkillMcpServers,
-  unmountSkillMcpServers,
-} from "../lib/skill-mcp.js";
 import {
   hasImageContent,
   toOllamaMessages,
@@ -99,6 +95,24 @@ import {
   beginManagedToolCheckpoint,
   settleManagedToolCheckpoint,
 } from "../lib/managed-tool-checkpoint.js";
+import {
+  createMcpCallLedger,
+  McpEffect,
+  snapshotMcpJsonRpcInput,
+} from "../lib/mcp-call-ledger.js";
+import {
+  MCP_OUTCOME_UNKNOWN_CODE,
+  markMcpLedgerOutcomeUnknown,
+} from "../lib/mcp-ledger-recovery-admission.js";
+import {
+  createHostOwnedMcpEffectContract,
+  createMcpConflictScheduler,
+} from "../lib/mcp-conflict-scheduler.js";
+import {
+  buildExtractiveHandoff,
+  formatStructuredHandoff,
+} from "../harness/structured-handoff.js";
+import { projectCanonicalResumeMessages } from "../lib/session-message-provenance.js";
 
 export { formatProviderHttpError };
 
@@ -114,13 +128,31 @@ export function getActiveMcpServers() {
   return new Set(_activeMcpServers);
 }
 
+// Direct executeTool callers do not pass agentLoop's run-scoped scheduler.
+// Share a bounded scheduler per MCP client so two concurrent calls cannot each
+// create a private lock and accidentally bypass unknown/write serialization.
+const _directMcpSchedulers = new WeakMap();
+function directMcpConflictScheduler(mcpClient) {
+  if (
+    (typeof mcpClient !== "object" || mcpClient === null) &&
+    typeof mcpClient !== "function"
+  ) {
+    return createMcpConflictScheduler({ maxActive: 1 });
+  }
+  let scheduler = _directMcpSchedulers.get(mcpClient);
+  if (!scheduler) {
+    scheduler = createMcpConflictScheduler();
+    _directMcpSchedulers.set(mcpClient, scheduler);
+  }
+  return scheduler;
+}
+
 const { isDangerousGitCommand, isReadOnlyGitCommand, normalizeGitCommand } =
   sharedCodingAgentPolicy;
 const { evaluateShellCommandPolicy } = sharedShellPolicy;
 const { evaluatePermissionRules } = sharedPermissionRules;
 const { collectHooks, umbrellaFor } = sharedSettingsHooks;
-const { runHooks: runCommandHooks, runHooksParallel: runCommandHooksParallel } =
-  sharedHookRunner;
+const { runHooks: runCommandHooks } = sharedHookRunner;
 const {
   runObserveHooks,
   aggregateContext,
@@ -635,19 +667,6 @@ function _resolveShellTimeout(raw) {
   return Math.min(Math.floor(n), MAX_SHELL_TIMEOUT_MS);
 }
 
-/**
- * Opt-in: run ALL matching decision hooks and take the STRICTEST outcome
- * (block > ask > allow > continue) instead of the default in-order first-wins
- * short-circuit — so an earlier hook's `ask` can no longer mask a later hook's
- * `block`. Default off = byte-identical short-circuit behavior. Flipping the
- * default is a product decision (all matching hooks then run every time, which
- * changes hook-execution volume + side effects).
- */
-function _hookStrictMergeEnabled() {
-  const v = process.env.CC_HOOK_STRICT_MERGE;
-  return v === "1" || v === "true";
-}
-
 /**
  * Run settings.json `PreToolUse` hooks (decision-capable). DB hooks are handled
  * separately + stay observe-only. A `block` decision stops the tool; an `ask`
@@ -677,18 +696,18 @@ async function runSettingsPreToolUseHooks(name, args, context, cwd) {
       parentId: context.hookParentId || null,
     },
   );
-  // Strict merge (opt-in) runs ALL matching hooks and takes the strictest
-  // decision. This path is async so the hooks run in TRUE PARALLEL
-  // (runHooksParallel) — wall-clock is the slowest hook, not their sum — while
-  // still yielding the same strictest outcome. Default path is the sync in-order
-  // short-circuit runner (byte-identical).
-  const outcome = _hookStrictMergeEnabled()
-    ? await runCommandHooksParallel(matched, payload, {
-        cwd,
-        event: "PreToolUse",
-        broker,
-      })
-    : runCommandHooks(matched, payload, { cwd, event: "PreToolUse", broker });
+  // Run every matching authority-bearing hook in configured order, then merge
+  // the outcomes with block > ask > allow > continue. Sequential execution
+  // preserves the documented hook side-effect order while preventing an early
+  // ask/allow from masking a later block. Environment variables cannot weaken
+  // this permission boundary.
+  const outcome = runCommandHooks(matched, payload, {
+    cwd,
+    event: "PreToolUse",
+    mergeStrict: true,
+    failClosed: true,
+    broker,
+  });
   if (outcome.decision === "block") {
     return { blocked: true, reason: outcome.reason, hook: outcome.hook };
   }
@@ -742,6 +761,10 @@ async function runSettingsPreToolUseHooks(name, args, context, cwd) {
  * @returns {{decision:("allow"|"deny"|null), reason?:string, hook?:string}}
  */
 function runSettingsPermissionRequestHooks(name, args, context, cwd, reason) {
+  // Command hooks are arbitrary processes. Until a host-enforced read-only
+  // hook sandbox exists, no command hook may execute inside the planning-only
+  // capability fence (even when the underlying tool is read-only).
+  if (context.planReadOnlyFenceActive === true) return { decision: null };
   const matched = collectHooks(
     context.settingsHooks,
     "PermissionRequest",
@@ -768,7 +791,8 @@ function runSettingsPermissionRequestHooks(name, args, context, cwd, reason) {
   const outcome = runCommandHooks(matched, payload, {
     cwd,
     event: "PermissionRequest",
-    mergeStrict: _hookStrictMergeEnabled(),
+    mergeStrict: true,
+    failClosed: true,
     broker,
   });
   // Precedence: deny > ask > allow > defer. The runner normalizes deny/block →
@@ -895,17 +919,21 @@ export function getAgentToolDefinitions({
   names = null,
   disabledTools = [],
   extraTools = [],
+  exactToolNames = false,
 } = {}) {
-  const allowedNames =
-    Array.isArray(names) && names.length > 0 ? new Set(names) : null;
-  const disabledNames = new Set(
-    Array.isArray(disabledTools) ? disabledTools : [],
-  );
+  // `names` historically selects a built-in tool preset while independently
+  // contributed host/MCP tools remain visible. Preserve that top-level behavior
+  // for a non-empty preset, but let authority-bearing child contexts opt into an
+  // exact all-tool ceiling. An explicit empty array is always deny-all.
+  const allowedNames = Array.isArray(names) ? new Set(names) : null;
   const extraToolNames = new Set(
     (Array.isArray(extraTools) ? extraTools : [])
       .map((tool) => tool?.function?.name)
       .filter(Boolean),
   );
+  const disabledNames = new Set(
+    Array.isArray(disabledTools) ? disabledTools : [],
+  );
   const allTools = mergeToolDefinitions(
     AGENT_TOOLS,
     Array.isArray(extraTools) ? extraTools : [],
@@ -914,7 +942,11 @@ export function getAgentToolDefinitions({
   return allTools.filter((tool) => {
     const name = tool?.function?.name;
     if (!name) return false;
-    if (allowedNames && !allowedNames.has(name) && !extraToolNames.has(name)) {
+    const unlistedExtraAllowed =
+      allowedNames?.size > 0 &&
+      exactToolNames !== true &&
+      extraToolNames.has(name);
+    if (allowedNames && !allowedNames.has(name) && !unlistedExtraAllowed) {
       return false;
     }
     if (disabledNames.has(name)) return false;
@@ -1598,7 +1630,8 @@ async function tryIdeDiffApprovalForEdit(
 ) {
   if (!IDE_DIFF_EDIT_TOOLS.has(name)) return null;
   if (typeof context.permissionConfirm !== "function") return null; // interactive only
-  if (!context.mcpClient || !context.externalToolExecutors) return null;
+  const hostMcpClient = context.mcpHostClient || context.mcpClient;
+  if (!hostMcpClient || !context.externalToolExecutors) return null;
   try {
     const {
       ideDiffApprovalEnabled,
@@ -1608,7 +1641,7 @@ async function tryIdeDiffApprovalForEdit(
       summarizeUserAmendments,
     } = await import("../lib/ide-context.js");
     const mcpLike = {
-      mcpClient: context.mcpClient,
+      mcpClient: hostMcpClient,
       externalToolExecutors: context.externalToolExecutors,
     };
     if (!ideDiffApprovalEnabled() || !hasIdeOpenDiff(mcpLike)) return null;
@@ -1722,6 +1755,19 @@ export async function executeTool(name, args, context = {}) {
   const skillLoader = context.skillLoader || _defaultSkillLoader;
   const cwd = context.cwd || process.cwd();
   const planManager = context.planManager || getPlanModeManager();
+  // The provider receives a filtered tool schema, but an untrusted/buggy model
+  // can still emit an arbitrary tool_call. Enforce the exact same immutable
+  // capability set again at execution time; null/absent preserves direct-call
+  // compatibility, while [] is an explicit deny-all ceiling.
+  if (
+    Array.isArray(context.effectiveAllowedToolNames) &&
+    !context.effectiveAllowedToolNames.includes(name)
+  ) {
+    return {
+      error: `[Tool Capability] Tool "${name}" is outside this run's effective tool set.`,
+      policy: { decision: "blocked", via: "effective-tool-set" },
+    };
+  }
   const localToolDescriptor =
     context.externalToolDescriptors &&
     typeof context.externalToolDescriptors === "object"
@@ -1789,11 +1835,60 @@ export async function executeTool(name, args, context = {}) {
   const workspacePathDenial = guardAgentFileToolPaths(name, args, context, cwd);
   if (workspacePathDenial) return workspacePathDenial;
 
+  // A malformed settings source may have hidden a deny/ask hook. Runtime
+  // loaders attach these parse failures as host-owned metadata; executing with
+  // a partial authority set would be strictly wider than the configured path.
+  const hookAuthorityErrors = context.settingsHooks?._authorityErrors;
+  if (Array.isArray(hookAuthorityErrors) && hookAuthorityErrors.length > 0) {
+    return {
+      error:
+        "[Hook Authority] Tool execution blocked because one or more hook policy sources could not be parsed.",
+      policy: { decision: "blocked", via: "hook-authority-load" },
+      incidents: hookAuthorityErrors.map((entry) => ({
+        sourceFile: entry?.sourceFile || entry?.file || null,
+        code: entry?.code || "CC_HOOK_AUTHORITY_INVALID",
+      })),
+    };
+  }
+
   const toolContext = createToolContext({
     toolName: runtimeDescriptor?.name || name,
     cwd,
     metadata: { descriptor: runtimeDescriptor },
   });
+  const observeHookIncidents = [];
+  const recordObserveHookIncident = (event, source, error) => {
+    const incident = Object.freeze({
+      code: "CC_HOOK_OBSERVER_DEGRADED",
+      event,
+      source,
+      degraded: true,
+      reason: String(error?.message || error || "hook observer failed")
+        .replace(/\s+/g, " ")
+        .slice(0, 240),
+    });
+    observeHookIncidents.push(incident);
+    try {
+      emitHooksV2Event("HookFailure", {
+        schema_version: 1,
+        session_id: context.sessionId || null,
+        turn_id: context.turnId || null,
+        tool_use_id: context.toolCallId || null,
+        tool_name: name,
+        hook_event_name: event,
+        hook_source: source,
+        incident_code: incident.code,
+      });
+    } catch {
+      // Incident delivery must never turn an observe-only failure into a new
+      // authority decision or hide the original tool outcome.
+    }
+    try {
+      context.onHookIncident?.(incident);
+    } catch {
+      // Optional observer only.
+    }
+  };
 
   // Persona toolsDisabled guard
   const persona = _loadProjectPersona(cwd);
@@ -1815,10 +1910,10 @@ export async function executeTool(name, args, context = {}) {
   //   3. settings `ask`   → confirm (headless w/o confirmer falls closed).
   //                         Reached only after BOTH denies clear, so a denied
   //                         tool never wastes a confirmation round-trip.
-  //   4. settings `allow` → pre-authorize (ruleAllowed): short-circuit the
-  //                         plan-mode block + run_shell ApprovalGate. The hard
-  //                         shell-policy denylist still applies — allow never
-  //                         re-enables an unsafe `rm -rf /`.
+  //   4. settings `allow` → pre-authorize interactive gates OUTSIDE the
+  //                         plan-mode hard ceiling. It can never add a tool to
+  //                         the planning/approved capability set. The hard
+  //                         shell-policy denylist also still applies.
   // No matching rule + no host policy → every existing layer runs unchanged
   // (default behaviour is byte-for-byte).
   const settingsVerdict = context.permissionRules
@@ -1849,18 +1944,10 @@ export async function executeTool(name, args, context = {}) {
     toolPolicies && typeof toolPolicies === "object"
       ? toolPolicies[name]
       : null;
-  const isExternalHostTool =
-    hostToolPolicy && !STATIC_AGENT_TOOL_NAMES.has(name);
-  const isExternalLocalTool =
-    localToolDescriptor && !STATIC_AGENT_TOOL_NAMES.has(name);
   const hostPolicyAllowsReadOnlyGit =
     name === "git" &&
     hostToolPolicy?.planModeBehavior === "readonly-conditional" &&
     isReadOnlyGitCommand(args.command);
-  const localReadOnlyAllowedInPlanMode =
-    isExternalLocalTool &&
-    planManager.isActive() &&
-    localToolDescriptor?.isReadOnly === true;
 
   // 2. host deny (a settings `allow` does not relax this)
   if (
@@ -1879,6 +1966,51 @@ export async function executeTool(name, args, context = {}) {
     };
   }
 
+  // Plan mode is a capability ceiling, not another prompt/approval source.
+  // Evaluate it before settings `ask`, sensitive-file confirmation, and every
+  // other interactive gate so no `allow` or confirmed `ask` can widen the
+  // planning tool set. Read-only git remains a built-in conditional capability.
+  // External tools remain blocked until a host-owned, per-tool effect authority
+  // exists; server annotations/descriptors cannot self-authorize Plan access.
+  const executionLockActive = planManager.executionLock != null;
+  const planReadOnlyFenceActive =
+    planManager.isActive() && !executionLockActive;
+  const externalToolBlockedDuringPlanning =
+    planReadOnlyFenceActive && !STATIC_AGENT_TOOL_NAMES.has(name);
+  context = { ...context, planReadOnlyFenceActive };
+  if (
+    planManager.isActive() &&
+    !(name === "git" && isReadOnlyGitCommand(args.command)) &&
+    (externalToolBlockedDuringPlanning || !planManager.isToolAllowed(name))
+  ) {
+    if (!executionLockActive) {
+      planManager.addPlanItem({
+        title: `${name}: ${formatToolArgs(name, args)}`,
+        tool: name,
+        params: args,
+        estimatedImpact:
+          name === "run_shell" ||
+          name === "run_code" ||
+          name === "git" ||
+          localToolDescriptor?.riskLevel === "high"
+            ? "high"
+            : GUARDED_FILE_MUTATION_TOOLS.has(name) ||
+                localToolDescriptor?.riskLevel === "medium"
+              ? "medium"
+              : "low",
+      });
+    }
+    return {
+      error: executionLockActive
+        ? `[Plan Execution Lock] Tool "${name}" was not in the approved tool set. Request a plan revision before using it.`
+        : `[Plan Mode] Tool "${name}" is blocked during planning. It has been added to the plan. Use /plan approve to execute.`,
+      policy: {
+        decision: "blocked",
+        via: executionLockActive ? "plan-execution-lock" : "plan-mode",
+      },
+    };
+  }
+
   // 3 + 4. settings ask / allow (only reached when neither layer denied)
   let ruleAllowed = false;
   if (settingsVerdict.decision === "ask") {
@@ -2062,43 +2194,17 @@ export async function executeTool(name, args, context = {}) {
     }
   }
 
-  // Plan mode: settings/host allow rules may help exploration, but they cannot
-  // widen the immutable tool set issued when the user approved the plan.
-  const executionLockActive = planManager.executionLock != null;
-  if (
-    planManager.isActive() &&
-    (!ruleAllowed || executionLockActive) &&
-    !(name === "git" && isReadOnlyGitCommand(args.command)) &&
-    !planManager.isToolAllowed(name) &&
-    !(
-      !executionLockActive &&
-      isExternalHostTool &&
-      hostToolPolicy?.allowed === true
-    ) &&
-    !(!executionLockActive && localReadOnlyAllowedInPlanMode)
-  ) {
-    if (!executionLockActive) {
-      planManager.addPlanItem({
-        title: `${name}: ${formatToolArgs(name, args)}`,
-        tool: name,
-        params: args,
-        estimatedImpact:
-          name === "run_shell" ||
-          name === "run_code" ||
-          name === "git" ||
-          localToolDescriptor?.riskLevel === "high"
-            ? "high"
-            : GUARDED_FILE_MUTATION_TOOLS.has(name) ||
-                localToolDescriptor?.riskLevel === "medium"
-              ? "medium"
-              : "low",
-      });
-    }
-    return {
-      error: executionLockActive
-        ? `[Plan Execution Lock] Tool "${name}" was not in the approved tool set. Request a plan revision before using it.`
-        : `[Plan Mode] Tool "${name}" is blocked during planning. It has been added to the plan. Use /plan approve to execute.`,
-    };
+  // Subtree rules are an authority input, so the first file mutation in a
+  // subtree must observe them before any PreToolUse hook or filesystem effect.
+  // Discovery+read commits the complete source/target batch atomically; this
+  // call is intentionally deferred once and succeeds only on an explicit retry.
+  if (GUARDED_FILE_MUTATION_TOOLS.has(name)) {
+    const instructionPreflight = await _preflightMutationSubtreeInstructions(
+      fileMutationPaths(name, args),
+      cwd,
+      context.subtreeInstructionScope || context.sessionId || "__legacy__",
+    );
+    if (instructionPreflight) return instructionPreflight;
   }
 
   // PreToolUse hooks. DB hooks (cc hook add) stay observe-only — a failure
@@ -2106,77 +2212,79 @@ export async function executeTool(name, args, context = {}) {
   // capable: a `block` (exit 2 / {decision:block}) stops the tool here, an
   // `ask` routes to the confirmer. Runs after permission resolution so a
   // settings deny / host deny short-circuits before any hook process spawns.
-  const hooksV2Pre = await executeHooksV2Event(
-    "PreToolUse",
-    {
-      schema_version: 1,
-      session_id: context.sessionId || null,
-      turn_id: context.turnId || null,
-      tool_use_id: context.toolCallId || null,
-      tool_name: name,
-      input_keys:
-        args && typeof args === "object" ? Object.keys(args).sort() : [],
-      cwd,
-    },
-    { failClosed: true },
-  );
-  if (hooksV2Pre.blocked || hooksV2Pre.decision === "block") {
-    return {
-      error: `[Hook v2] PreToolUse blocked "${name}".`,
-      policy: { decision: "block", via: "hooks-v2" },
-    };
-  }
-  if (hooksV2Pre.requiresApproval || hooksV2Pre.decision === "ask") {
-    const confirm = context.permissionConfirm || context.shellConfirm || null;
-    const approved =
-      typeof confirm === "function"
-        ? await confirm({
-            tool: name,
-            args,
-            reason: "Hooks v2 PreToolUse requested confirmation",
-            source: "hooks-v2",
-          })
-        : false;
-    if (!approved) {
-      emitHooksV2Event("PermissionDenied", {
+  if (!planReadOnlyFenceActive) {
+    const hooksV2Pre = await executeHooksV2Event(
+      "PreToolUse",
+      {
         schema_version: 1,
         session_id: context.sessionId || null,
         turn_id: context.turnId || null,
         tool_use_id: context.toolCallId || null,
         tool_name: name,
-        source: "hooks-v2",
-      });
+        input_keys:
+          args && typeof args === "object" ? Object.keys(args).sort() : [],
+        cwd,
+      },
+      { failClosed: true },
+    );
+    if (hooksV2Pre.blocked || hooksV2Pre.decision === "block") {
       return {
-        error: `[Hook v2] PreToolUse confirmation denied for "${name}".`,
-        policy: { decision: "deny", via: "hooks-v2" },
+        error: `[Hook v2] PreToolUse blocked "${name}".`,
+        policy: { decision: "block", via: "hooks-v2" },
       };
     }
-  }
-  if (hookDb) {
-    try {
-      await executeHooks(hookDb, HookEvents.PreToolUse, {
-        tool: name,
-        args,
-        timestamp: new Date().toISOString(),
-        descriptor: runtimeDescriptor,
-        context: toolContext,
-      });
-    } catch (_err) {
-      // Hook failure should not block tool execution
+    if (hooksV2Pre.requiresApproval || hooksV2Pre.decision === "ask") {
+      const confirm = context.permissionConfirm || context.shellConfirm || null;
+      const approved =
+        typeof confirm === "function"
+          ? await confirm({
+              tool: name,
+              args,
+              reason: "Hooks v2 PreToolUse requested confirmation",
+              source: "hooks-v2",
+            })
+          : false;
+      if (!approved) {
+        emitHooksV2Event("PermissionDenied", {
+          schema_version: 1,
+          session_id: context.sessionId || null,
+          turn_id: context.turnId || null,
+          tool_use_id: context.toolCallId || null,
+          tool_name: name,
+          source: "hooks-v2",
+        });
+        return {
+          error: `[Hook v2] PreToolUse confirmation denied for "${name}".`,
+          policy: { decision: "deny", via: "hooks-v2" },
+        };
+      }
     }
-  }
-  if (context.settingsHooks) {
-    const pre = await runSettingsPreToolUseHooks(name, args, context, cwd);
-    // A hook `ask` resolved by the IDE diff review: accepted → the IDE
-    // already wrote the file, return the synthetic result and skip the tool;
-    // rejected → the ide-diff deny shape (via:"ide-diff", not via:"hook").
-    if (pre.ideApplied) return pre.ideApplied;
-    if (pre.blocked) {
-      if (pre.ideResult) return pre.ideResult;
-      return {
-        error: `[Hook] PreToolUse blocked "${name}"${pre.reason ? ": " + pre.reason : ""}`,
-        policy: { decision: "block", via: "hook", hook: pre.hook || null },
-      };
+    if (hookDb) {
+      try {
+        await executeHooks(hookDb, HookEvents.PreToolUse, {
+          tool: name,
+          args,
+          timestamp: new Date().toISOString(),
+          descriptor: runtimeDescriptor,
+          context: toolContext,
+        });
+      } catch (error) {
+        recordObserveHookIncident("PreToolUse", "database", error);
+      }
+    }
+    if (context.settingsHooks) {
+      const pre = await runSettingsPreToolUseHooks(name, args, context, cwd);
+      // A hook `ask` resolved by the IDE diff review: accepted → the IDE
+      // already wrote the file, return the synthetic result and skip the tool;
+      // rejected → the ide-diff deny shape (via:"ide-diff", not via:"hook").
+      if (pre.ideApplied) return pre.ideApplied;
+      if (pre.blocked) {
+        if (pre.ideResult) return pre.ideResult;
+        return {
+          error: `[Hook] PreToolUse blocked "${name}"${pre.reason ? ": " + pre.reason : ""}`,
+          policy: { decision: "block", via: "hook", hook: pre.hook || null },
+        };
+      }
     }
   }
 
@@ -2201,10 +2309,18 @@ export async function executeTool(name, args, context = {}) {
       // 用量归因: shared per-run sink for child-loop (sub-agent / isolated
       // skill) token usage, drained by agentLoop as attributed events.
       subAgentUsageSink: context.subAgentUsageSink || null,
+      planManager,
+      permissionRules: context.permissionRules || null,
+      effectiveAllowedToolNames: context.effectiveAllowedToolNames ?? null,
       hostManagedToolPolicy: context.hostManagedToolPolicy || null,
       externalToolDescriptors: context.externalToolDescriptors || null,
       externalToolExecutors: context.externalToolExecutors || null,
       mcpClient: context.mcpClient || null,
+      mcpHostClient: context.mcpHostClient || context.mcpClient || null,
+      mcpCallLedger: context.mcpCallLedger || null,
+      mcpConflictScheduler: context.mcpConflictScheduler || null,
+      subtreeInstructionScope:
+        context.subtreeInstructionScope || context.sessionId || "__legacy__",
       shellPolicyOverrides: context.shellPolicyOverrides || null,
       approvalGate: context.approvalGate || null,
       shellConfirm: context.shellConfirm || null,
@@ -2214,6 +2330,7 @@ export async function executeTool(name, args, context = {}) {
       settingsVerdict,
       subAgentDepth: context.subAgentDepth || 0,
       subAgentBudget: context.subAgentBudget || null,
+      sessionBudget: context.sessionBudget || null,
       // Effective contract of THIS loop (parent ceiling for a nested spawn) +
       // the MCP tool definitions this loop exposes (inheritable by a spawn).
       subAgentContract: context.subAgentContract || null,
@@ -2230,15 +2347,15 @@ export async function executeTool(name, args, context = {}) {
       managedCheckpoint: context.managedCheckpoint === true,
     });
   } catch (err) {
-    if (hookDb) {
+    if (hookDb && !planReadOnlyFenceActive) {
       try {
         await executeHooks(hookDb, HookEvents.ToolError, {
           tool: name,
           args,
           error: err.message,
         });
-      } catch (_err) {
-        // Non-critical
+      } catch (error) {
+        recordObserveHookIncident("ToolError", "database", error);
       }
     }
     throw err;
@@ -2261,7 +2378,7 @@ export async function executeTool(name, args, context = {}) {
   }
 
   // PostToolUse hook
-  if (hookDb) {
+  if (hookDb && !planReadOnlyFenceActive) {
     try {
       await executeHooks(hookDb, HookEvents.PostToolUse, {
         tool: name,
@@ -2273,13 +2390,18 @@ export async function executeTool(name, args, context = {}) {
         descriptor: runtimeDescriptor,
         context: toolContext,
       });
-    } catch (_err) {
-      // Non-critical
+    } catch (error) {
+      recordObserveHookIncident("PostToolUse", "database", error);
     }
   }
   // settings.json PostToolUse hooks: can't un-run the tool, but a `block`
   // reason is attached as `hookFeedback` to be surfaced back to the model.
-  if (context.settingsHooks && toolResult && typeof toolResult === "object") {
+  if (
+    !planReadOnlyFenceActive &&
+    context.settingsHooks &&
+    toolResult &&
+    typeof toolResult === "object"
+  ) {
     try {
       const matched = collectHooks(context.settingsHooks, "PostToolUse", name);
       if (matched && matched.length > 0) {
@@ -2314,6 +2436,20 @@ export async function executeTool(name, args, context = {}) {
             event: "PostToolUse",
             broker,
           });
+          for (const hookResult of outcome.results || []) {
+            if (
+              hookResult?.nonBlockingError === true ||
+              hookResult?.breakerOpen === true ||
+              hookResult?.malformedDecision === true ||
+              hookResult?.unsupportedDecision === true
+            ) {
+              recordObserveHookIncident(
+                "PostToolUse",
+                "settings-command",
+                hookResult.reason || hookResult.error || "hook command failed",
+              );
+            }
+          }
           if (outcome.decision === "block" && outcome.reason) {
             toolResult.hookFeedback = outcome.reason;
           }
@@ -2324,8 +2460,8 @@ export async function executeTool(name, args, context = {}) {
           context.hookSupervisor.dispatch(asyncHooks, payload, { cwd, broker });
         }
       }
-    } catch (_err) {
-      // PostToolUse hooks are best-effort
+    } catch (error) {
+      recordObserveHookIncident("PostToolUse", "settings-command", error);
     }
   }
 
@@ -2366,8 +2502,8 @@ export async function executeTool(name, args, context = {}) {
           ? `${toolResult.hookFeedback}\n${outcome.reason}`
           : outcome.reason;
       }
-    } catch (_err) {
-      // SubagentStop hooks are best-effort
+    } catch (error) {
+      recordObserveHookIncident("SubagentStop", "settings-command", error);
     }
   }
 
@@ -2385,7 +2521,7 @@ export async function executeTool(name, args, context = {}) {
     typeof toolResult === "object" &&
     !toolResult.error &&
     args?.path &&
-    context.mcpClient &&
+    (context.mcpHostClient || context.mcpClient) &&
     context.externalToolExecutors
   ) {
     try {
@@ -2393,7 +2529,7 @@ export async function executeTool(name, args, context = {}) {
         await import("../lib/ide-context.js");
       const diags = await collectIdeDiagnostics(
         {
-          mcpClient: context.mcpClient,
+          mcpClient: context.mcpHostClient || context.mcpClient,
           externalToolExecutors: context.externalToolExecutors,
         },
         path.resolve(cwd, args.path),
@@ -2405,6 +2541,14 @@ export async function executeTool(name, args, context = {}) {
     }
   }
 
+  if (
+    observeHookIncidents.length > 0 &&
+    toolResult &&
+    typeof toolResult === "object"
+  ) {
+    toolResult.hookIncidents = observeHookIncidents;
+  }
+
   return toolResult;
 }
 
@@ -2898,15 +3042,20 @@ export async function _withPostEditDiagnostics(
 // NOT loaded up front — they cost tokens for subtrees a run may never touch.
 // When a tool first ACCESSES a path inside such a subtree, we inject that
 // subtree's directory instructions into the tool result (the SAME channel as
-// newDiagnostics), exactly once per subtree per process. A stateful
-// SubtreeInstructionLoader per root remembers what it already injected so a
+// newDiagnostics), exactly once per subtree per agent session. A stateful
+// SubtreeInstructionLoader per root/session remembers what it already injected so a
 // second access to the same subtree is a no-op. Disable with
 // CC_SUBTREE_INSTRUCTIONS=0. Common case (no cc.md below cwd) → zero cost.
-const _subtreeLoaderPool = new Map(); // root -> SubtreeInstructionLoader
+const _subtreeLoaderPool = new Map(); // root -> Map<session scope, loader>
 
-async function _getSubtreeLoader(cwd) {
+async function _getSubtreeLoader(cwd, sessionScope = "__legacy__") {
   const root = path.resolve(cwd || process.cwd());
-  let loader = _subtreeLoaderPool.get(root);
+  let scopedLoaders = _subtreeLoaderPool.get(root);
+  if (!scopedLoaders) {
+    scopedLoaders = new Map();
+    _subtreeLoaderPool.set(root, scopedLoaders);
+  }
+  let loader = scopedLoaders.get(sessionScope);
   if (!loader) {
     const { SubtreeInstructionLoader } =
       await import("../lib/project-instructions.js");
@@ -2925,7 +3074,7 @@ async function _getSubtreeLoader(cwd) {
       baseDir: root,
       instructionExcludes,
     });
-    _subtreeLoaderPool.set(root, loader);
+    scopedLoaders.set(sessionScope, loader);
   }
   return loader;
 }
@@ -2940,15 +3089,28 @@ export function _resetSubtreeInstructionLoaders() {
  * with their (capped) content read for inline injection — or null when the
  * subtree has no NEW cc.md/CLAUDE.md/AGENTS.md (the common case → zero cost).
  */
-async function _subtreeInstructionsFor(accessedPath, cwd) {
+async function _prepareSubtreeInstructions(
+  accessedPaths,
+  cwd,
+  sessionScope = "__legacy__",
+) {
   if (process.env.CC_SUBTREE_INSTRUCTIONS === "0") return null;
   try {
-    const loader = await _getSubtreeLoader(cwd);
-    const fresh = loader.onAccess(accessedPath);
+    const loader = await _getSubtreeLoader(cwd, sessionScope);
+    const discovered = new Map();
+    for (const accessedPath of Array.isArray(accessedPaths)
+      ? accessedPaths
+      : [accessedPaths]) {
+      for (const candidate of loader.discover(accessedPath)) {
+        discovered.set(candidate.identity, candidate);
+      }
+    }
+    const fresh = [...discovered.values()];
     if (!fresh || !fresh.length) return null;
     const { DEFAULT_MAX_FILE_BYTES } =
       await import("../lib/project-instructions.js");
     const out = [];
+    const errors = [];
     for (const f of fresh) {
       try {
         const buf = fs.readFileSync(f.path);
@@ -2962,23 +3124,84 @@ async function _subtreeInstructionsFor(accessedPath, cwd) {
           content,
           ...(truncated ? { truncated: true } : {}),
         });
-      } catch {
-        // discovered file vanished before we could read it — skip it
+      } catch (err) {
+        errors.push({ path: f.path, message: err.message });
       }
     }
-    return out.length ? out : null;
-  } catch {
-    return null; // fail-open: never break a tool because injection errored
+    // Commit only after every candidate in the source/target batch has been
+    // read. Any failure leaves the entire batch discoverable for a retry.
+    if (!errors.length) loader.commit(fresh);
+    return out.length || errors.length ? { instructions: out, errors } : null;
+  } catch (err) {
+    // Paths outside cwd are handled by the normal path/sandbox authority and
+    // have no cwd-subtree rules. Other failures remain visible to mutation
+    // preflight so they cannot silently widen authority.
+    if (err?.code === "ERR_SUBTREE_INSTRUCTION_BOUNDARY") return null;
+    return {
+      instructions: [],
+      errors: [{ path: null, message: err?.message || String(err) }],
+    };
+  }
+}
+
+async function _subtreeInstructionsFor(accessedPath, cwd, sessionScope) {
+  const prepared = await _prepareSubtreeInstructions(
+    accessedPath,
+    cwd,
+    sessionScope,
+  );
+  return prepared?.instructions?.length ? prepared.instructions : null;
+}
+
+async function _preflightMutationSubtreeInstructions(
+  accessedPaths,
+  cwd,
+  sessionScope,
+) {
+  const prepared = await _prepareSubtreeInstructions(
+    accessedPaths,
+    cwd,
+    sessionScope,
+  );
+  if (!prepared) return null;
+  if (prepared.errors?.length) {
+    return {
+      error:
+        "[Subtree Instructions] Mutation blocked because applicable instructions could not be loaded. No mutation was performed.",
+      policy: { decision: "blocked", via: "subtree-instructions" },
+      instructionLoadErrors: prepared.errors,
+      mutationPerformed: false,
+      ...(prepared.instructions?.length
+        ? { subtreeInstructions: prepared.instructions }
+        : {}),
+    };
   }
+  if (!prepared.instructions?.length) return null;
+  return {
+    error:
+      "[Subtree Instructions] Mutation deferred before its first effect. Review these authoritative subtree rules, then retry the tool call.",
+    policy: { decision: "deferred", via: "subtree-instructions" },
+    subtreeInstructions: prepared.instructions,
+    mutationPerformed: false,
+  };
 }
 
 /**
  * Attach freshly-discovered subtree instructions to a SUCCESSFUL tool result
  * (no-op on an error result or when the subtree has nothing new).
  */
-async function _withSubtreeInstructions(result, accessedPath, cwd) {
+async function _withSubtreeInstructions(
+  result,
+  accessedPath,
+  cwd,
+  sessionScope,
+) {
   if (result && result.error) return result;
-  const subtreeInstructions = await _subtreeInstructionsFor(accessedPath, cwd);
+  const subtreeInstructions = await _subtreeInstructionsFor(
+    accessedPath,
+    cwd,
+    sessionScope,
+  );
   return subtreeInstructions ? { ...result, subtreeInstructions } : result;
 }
 
@@ -3035,6 +3258,168 @@ async function promoteBrowserScreenshot(
   }
 }
 
+const MCP_LEDGER_EFFECTS = new Set(["read", "unknown", "write", "destructive"]);
+
+/**
+ * Reduce descriptor + managed-host metadata to the host-owned contract written
+ * to the MCP ledger. A server's read-only declaration is never promoted to a
+ * read authorization. Server declarations may only make the classification
+ * stricter (write/destructive) when host authority is absent.
+ */
+function mcpLedgerEffectContract(descriptor, hostPolicy) {
+  const descriptorContract = descriptor?.effectContract || {};
+  const hostContract = hostPolicy?.effectContract || {};
+  const authorizedCandidate =
+    hostContract.authorizedEffect || hostPolicy?.authorizedEffect;
+  const authorizedEffect = MCP_LEDGER_EFFECTS.has(authorizedCandidate)
+    ? authorizedCandidate
+    : null;
+  const declaredEffect = MCP_LEDGER_EFFECTS.has(
+    descriptorContract.declaredEffect,
+  )
+    ? descriptorContract.declaredEffect
+    : "unknown";
+  const effect =
+    authorizedEffect ||
+    (declaredEffect === "destructive" || declaredEffect === "write"
+      ? declaredEffect
+      : "unknown");
+  const annotations = descriptorContract.annotations || {};
+
+  return {
+    effect,
+    destructive:
+      effect === "destructive" || annotations.destructiveHint === true,
+    sideEffecting: effect === "write" || effect === "destructive",
+    idempotent:
+      typeof annotations.idempotentHint === "boolean"
+        ? annotations.idempotentHint
+        : null,
+    openWorld:
+      typeof annotations.openWorldHint === "boolean"
+        ? annotations.openWorldHint
+        : null,
+    trusted:
+      authorizedEffect != null &&
+      (hostContract.trusted === true || hostPolicy?.sourceTrusted === true),
+    source:
+      hostContract.provenance ||
+      descriptorContract.provenance ||
+      descriptor?.source ||
+      "mcp",
+  };
+}
+
+function mcpLedgerScopes(args) {
+  const resourceScopes = [];
+  const networkScopes = [];
+  const visit = (value, key = "", depth = 0) => {
+    if (depth > 3 || value == null) return;
+    if (Array.isArray(value)) {
+      value.slice(0, 32).forEach((entry) => visit(entry, key, depth + 1));
+      return;
+    }
+    if (typeof value === "object") {
+      Object.entries(value)
+        .slice(0, 64)
+        .forEach(([childKey, childValue]) =>
+          visit(childValue, childKey, depth + 1),
+        );
+      return;
+    }
+    if (typeof value !== "string") return;
+
+    const normalizedKey = String(key).toLowerCase();
+    const isNetworkScope = /url|uri|endpoint|origin|host/.test(normalizedKey);
+    if (isNetworkScope) {
+      networkScopes.push(value);
+    }
+    // URL/URI values can carry credentials, query secrets and private paths.
+    // The network ledger normalizes them to origin only; never duplicate the
+    // raw value into resourceScopes, whose identifiers are intentionally not
+    // URL parsers. The input digest still binds the exact request at rest.
+    if (
+      !isNetworkScope &&
+      /path|file|resource|repo|project|workspace/.test(normalizedKey)
+    ) {
+      resourceScopes.push(`${normalizedKey}:${value}`);
+    }
+  };
+  visit(args || {});
+  return { resourceScopes, networkScopes };
+}
+
+const MCP_TRANSPORT_OUTCOME_UNKNOWN_CODE = "CC_MCP_TRANSPORT_OUTCOME_UNKNOWN";
+const MCP_PROTOCOL_RESULT_INVALID_CODE = "CC_MCP_PROTOCOL_RESULT_INVALID";
+const MCP_RESULT_PROJECTION_FAILED_CODE = "CC_MCP_RESULT_PROJECTION_FAILED";
+
+function safeMcpProperty(value, property) {
+  try {
+    return value?.[property];
+  } catch {
+    return undefined;
+  }
+}
+
+function safeMcpErrorMessage(error) {
+  const message = safeMcpProperty(error, "message");
+  if (typeof message === "string" && message) return message;
+  try {
+    return String(error || "unknown error");
+  } catch {
+    return "unknown error";
+  }
+}
+
+function safeMcpErrorCode(error, fallback) {
+  const code = safeMcpProperty(error, "code");
+  return typeof code === "string" && code ? code : fallback;
+}
+
+function invalidMcpProtocolResult(cause) {
+  const error = new TypeError("MCP result could not be inspected safely", {
+    cause,
+  });
+  error.code = MCP_PROTOCOL_RESULT_INVALID_CODE;
+  return error;
+}
+
+function mcpTransportOutcomeIsUnsafe(effectContract) {
+  return !(
+    effectContract?.effect === McpEffect.READ &&
+    effectContract?.trusted === true
+  );
+}
+
+function mcpOutcomeUnknownPayload(
+  ledger,
+  ticket,
+  { phase, reasonCode = MCP_OUTCOME_UNKNOWN_CODE } = {},
+) {
+  const stableReasonCode =
+    typeof reasonCode === "string" && reasonCode
+      ? reasonCode
+      : MCP_OUTCOME_UNKNOWN_CODE;
+  try {
+    markMcpLedgerOutcomeUnknown(ledger, stableReasonCode);
+  } catch {
+    // The public result must remain deterministic even for a hostile ledger.
+  }
+  return {
+    error:
+      "MCP tool may have completed, but its outcome is unknown; do not retry automatically until durable recovery is adjudicated.",
+    code: MCP_OUTCOME_UNKNOWN_CODE,
+    status: "outcome_unknown",
+    outcomeUnknown: true,
+    retryable: false,
+    mcpLedgerId: safeMcpProperty(ticket, "ledgerId") || null,
+    mcpLedgerIncident: {
+      phase: phase || "settled",
+      code: stableReasonCode,
+    },
+  };
+}
+
 async function executeToolInner(
   name,
   args,
@@ -3047,11 +3432,17 @@ async function executeToolInner(
     sessionId,
     turnId,
     toolCallId,
+    planManager = null,
+    permissionRules = null,
+    effectiveAllowedToolNames = null,
     hostManagedToolPolicy,
     externalToolDescriptors,
     externalToolExecutors,
     extraToolDefinitions = null,
     mcpClient,
+    mcpCallLedger = null,
+    mcpConflictScheduler = null,
+    subtreeInstructionScope = "__legacy__",
     memoryDb = null,
     permanentMemory = null,
     subAgentContract = null,
@@ -3066,6 +3457,7 @@ async function executeToolInner(
     settingsVerdict = null,
     subAgentDepth = 0,
     subAgentBudget = null,
+    sessionBudget = null,
     interactiveApproval = false,
     settingsHooks = null,
     signal = null,
@@ -3195,6 +3587,7 @@ async function executeToolInner(
             },
             filePath,
             cwd,
+            subtreeInstructionScope,
           ),
         );
       }
@@ -3207,6 +3600,7 @@ async function executeToolInner(
           },
           filePath,
           cwd,
+          subtreeInstructionScope,
         ),
       );
     }
@@ -3237,6 +3631,7 @@ async function executeToolInner(
           ),
           filePath,
           cwd,
+          subtreeInstructionScope,
         ),
       );
     }
@@ -3318,6 +3713,7 @@ async function executeToolInner(
           ),
           targetPath,
           cwd,
+          subtreeInstructionScope,
         ),
       );
     }
@@ -3418,6 +3814,7 @@ async function executeToolInner(
           ),
           filePath,
           cwd,
+          subtreeInstructionScope,
         ),
       );
     }
@@ -3483,6 +3880,7 @@ async function executeToolInner(
           ),
           filePath,
           cwd,
+          subtreeInstructionScope,
         ),
       );
     }
@@ -4444,13 +4842,28 @@ async function executeToolInner(
           llmOptions,
           subAgentDepth,
           subAgentBudget,
+          sessionBudget,
           subAgentContract,
           settingsHooks,
+          // Immutable parent execution authority. The child may only tighten
+          // these boundaries; it never reconstructs a fresh default policy.
+          planManager,
+          permissionRules,
+          effectiveAllowedToolNames,
+          hostManagedToolPolicy,
+          sandbox,
+          additionalDirectories,
+          approvalGate,
+          shellPolicyOverrides,
+          classifyAllShell,
+          unattendedActionPolicy,
           // Parent trace for the child's hook envelopes (parent_id).
           hookTraceId,
           // Parent MCP plumbing — a spawn can inherit these into the child,
           // filtered by the resolved contract's mcpServers allow-list.
           mcpClient,
+          mcpCallLedger,
+          mcpConflictScheduler,
           externalToolDescriptors,
           externalToolExecutors,
           extraToolDefinitions,
@@ -4522,14 +4935,31 @@ async function executeToolInner(
     case "todo_write": {
       try {
         const { writeTodos } = await import("../lib/todo-manager.js");
-        const result = writeTodos(sessionId, args.todos);
+        const result = writeTodos(sessionId, args.todos, {
+          ...(Number.isSafeInteger(args.expected_revision)
+            ? { expectedRevision: args.expected_revision }
+            : {}),
+        });
         if (!result.success) {
-          return attachDescriptor({ error: result.error });
+          return attachDescriptor({
+            error: result.error,
+            ...(result.code ? { code: result.code } : {}),
+            ...(Number.isSafeInteger(result.expectedRevision)
+              ? { expectedRevision: result.expectedRevision }
+              : {}),
+            ...(Number.isSafeInteger(result.actualRevision)
+              ? { actualRevision: result.actualRevision }
+              : {}),
+            ...(result.recoveryStrategy
+              ? { recoveryStrategy: result.recoveryStrategy }
+              : {}),
+          });
         }
         return attachDescriptor({
           success: true,
           count: result.count,
           summary: result.summary,
+          revision: result.revision,
         });
       } catch (err) {
         return attachDescriptor({ error: `todo_write failed: ${err.message}` });
@@ -5218,6 +5648,7 @@ async function executeToolInner(
           },
           dirPath,
           cwd,
+          subtreeInstructionScope,
         ),
       );
     }
@@ -5243,7 +5674,14 @@ async function executeToolInner(
         });
       }
       try {
-        if (typeof skillLoader.materializeSkill === "function") {
+        if (typeof skillLoader.materializeSkillForExecution === "function") {
+          match = await skillLoader.materializeSkillForExecution(match, {
+            sessionId,
+            turnId,
+            loadedBecause: "run_skill",
+            bodyIncluded: false,
+          });
+        } else if (typeof skillLoader.materializeSkill === "function") {
           match = skillLoader.materializeSkill(match, {
             sessionId,
             turnId,
@@ -5254,12 +5692,26 @@ async function executeToolInner(
       } catch (error) {
         return attachDescriptor({
           error: `Skill "${args.skill_name}" body could not be loaded: ${error.message}`,
+          ...(error?.code ? { code: error.code } : {}),
+          policy: {
+            decision: "blocked",
+            via: "skill-execution-boundary",
+          },
         });
       }
 
       // Check if skill requests isolation (via SKILL.md frontmatter)
       const skillIsolation = match.isolation === true;
       if (skillIsolation) {
+        const isolatedSkillTools = [
+          "read_file",
+          "search_files",
+          "list_dir",
+        ].filter(
+          (toolName) =>
+            !Array.isArray(effectiveAllowedToolNames) ||
+            effectiveAllowedToolNames.includes(toolName),
+        );
         // 用量归因: an isolated skill runs as a child loop whose real token
         // usage would otherwise be invisible — forward it into the parent
         // run's sink tagged origin:"skill" so `cc session usage --by skill`
@@ -5271,11 +5723,36 @@ async function executeToolInner(
         // Run skill through isolated sub-agent context
         const subCtx = SubAgentContext.create({
           role: `skill-${args.skill_name}`,
-          task: `Execute the "${args.skill_name}" skill with input: ${(args.input || "").substring(0, 200)}`,
-          allowedTools: ["read_file", "search_files", "list_dir"],
+          task:
+            `Execute the "${args.skill_name}" skill using only the approved tools.\n\n` +
+            `Authoritative skill instructions:\n${String(match.body || "").substring(0, 48000)}\n\n` +
+            `User input:\n${String(args.input || "").substring(0, 8000)}`,
+          allowedTools: isolatedSkillTools,
           hookParentTraceId: hookTraceId || null,
           toolAdmission,
           cwd,
+          llmOptions: llmOptions || null,
+          ...(sessionBudget ? { sessionBudget } : {}),
+          ...(permissionRules ? { permissionRules } : {}),
+          ...(hostManagedToolPolicy
+            ? {
+                hostManagedToolPolicy: {
+                  ...hostManagedToolPolicy,
+                  toolDefinitions: [],
+                },
+              }
+            : {}),
+          ...(planManager ? { planManager } : {}),
+          ...(sandbox ? { sandbox } : {}),
+          ...(Array.isArray(additionalDirectories)
+            ? { additionalDirectories: [...additionalDirectories] }
+            : {}),
+          ...(approvalGate ? { approvalGate } : {}),
+          ...(shellPolicyOverrides ? { shellPolicyOverrides } : {}),
+          ...(classifyAllShell ? { classifyAllShell: true } : {}),
+          ...(unattendedActionPolicy ? { unattendedActionPolicy } : {}),
+          ...(mcpCallLedger ? { mcpCallLedger } : {}),
+          ...(mcpConflictScheduler ? { mcpConflictScheduler } : {}),
           onUsage: skillUsageSink
             ? (u) => {
                 try {
@@ -5286,6 +5763,7 @@ async function executeToolInner(
                           provider: u?.provider ?? null,
                           model: u?.model ?? null,
                           usage: u?.usage || null,
+                          ...(u?.source ? { source: u.source } : {}),
                           attribution: {
                             origin: "skill",
                             skill: args.skill_name,
@@ -5304,6 +5782,25 @@ async function executeToolInner(
         skillSubRef = subCtx;
         try {
           const result = await subCtx.run(args.input);
+          const resolvedFailure =
+            subCtx.status === "failed" ||
+            result?.success === false ||
+            Boolean(result?.error);
+          if (resolvedFailure) {
+            const failureDetail =
+              result?.error?.message ||
+              result?.error ||
+              result?.summary ||
+              `child status ${subCtx.status || "failed"}`;
+            return attachDescriptor({
+              success: false,
+              isolated: true,
+              skill: args.skill_name,
+              code: result?.code || "CC_SKILL_ISOLATED_EXECUTION_FAILED",
+              error: `Isolated skill execution failed: ${failureDetail}`,
+              ...(result?.summary ? { summary: result.summary } : {}),
+            });
+          }
           return attachDescriptor({
             success: true,
             isolated: true,
@@ -5313,79 +5810,24 @@ async function executeToolInner(
           });
         } catch (err) {
           return attachDescriptor({
+            success: false,
+            isolated: true,
+            skill: args.skill_name,
+            code: err?.code || "CC_SKILL_ISOLATED_EXECUTION_FAILED",
             error: `Isolated skill execution failed: ${err.message}`,
           });
         }
       }
 
-      // Skill-Embedded MCP: mount the skill's declared MCP servers for
-      // the duration of handler.execute, then unmount in finally. The
-      // handler may use them via taskContext.mcpClient. If mcpClient is
-      // null (no MCP set up for this session), skip silently.
-      let mountedMcpServers = [];
-      const hasSkillMcps =
-        Array.isArray(match.mcpServers) && match.mcpServers.length > 0;
-      if (hasSkillMcps && mcpClient) {
-        try {
-          const mountResult = await mountSkillMcpServers(mcpClient, match, {
-            onWarn: (msg) => {
-              // Non-fatal — logged as warning, skipped servers captured
-              // in mountResult.skipped.
-
-              console.warn(msg);
-            },
-          });
-          mountedMcpServers = mountResult.mounted;
-          for (const s of mountedMcpServers) {
-            _activeMcpServers.add(typeof s === "string" ? s : s.name);
-          }
-        } catch (err) {
-          return attachDescriptor({
-            error: `Skill MCP mount failed: ${err.message}`,
-          });
-        }
-      }
-
-      try {
-        const handlerPath = path.join(match.skillDir, "handler.js");
-        const imported = await import(
-          `file://${handlerPath.replace(/\\/g, "/")}`
-        );
-        const handler = imported.default || imported;
-        if (handler.init) await handler.init(match);
-        const task = {
-          params: { input: args.input },
-          input: args.input,
-          action: args.input,
-        };
-        const taskContext = {
-          projectRoot: cwd,
-          workspacePath: cwd,
-          processBroker: createSkillProcessBroker(match),
-          // Expose the MCP client + mounted servers so the skill handler
-          // can call MCP tools directly without going through the agent
-          // loop. Handlers that don't need MCP can ignore these.
-          mcpClient: mcpClient || null,
-          mountedMcpServers,
-        };
-        const result = await handler.execute(task, taskContext, match);
-        return attachDescriptor(result);
-      } catch (err) {
-        return attachDescriptor({
-          error: `Skill execution failed: ${err.message}`,
-        });
-      } finally {
-        if (mountedMcpServers.length > 0 && mcpClient) {
-          try {
-            await unmountSkillMcpServers(mcpClient, mountedMcpServers);
-          } catch (_err) {
-            // Non-critical — mount/unmount errors don't fail the skill
-          }
-          for (const s of mountedMcpServers) {
-            _activeMcpServers.delete(typeof s === "string" ? s : s.name);
-          }
-        }
-      }
+      // Defense in depth: materializeSkill currently rejects this path before
+      // reaching here. Keep the runtime fence explicit so a custom/legacy
+      // loader can never re-enable arbitrary handler.js imports in the CLI
+      // process or hand a Skill the raw MCP client/process broker.
+      return attachDescriptor({
+        error: `Skill "${args.skill_name}" cannot execute handler.js directly. Add isolation: true and use the controlled agent-tool path.`,
+        code: "CC_SKILL_DIRECT_HANDLER_BLOCKED",
+        policy: { decision: "blocked", via: "skill-execution-boundary" },
+      });
     }
 
     case "list_skills": {
@@ -5501,21 +5943,268 @@ async function executeToolInner(
           return attachDescriptor(deferredGate);
         }
 
+        let mcpWireInput;
+        try {
+          mcpWireInput = snapshotMcpJsonRpcInput(args || {});
+        } catch (error) {
+          return attachDescriptor({
+            error:
+              "MCP tool blocked because its input is not strict immutable JSON data",
+            policy: {
+              decision: "blocked",
+              via: "mcp-wire-input",
+              code: safeMcpErrorCode(error, "CC_MCP_WIRE_INPUT_INVALID"),
+            },
+          });
+        }
+
+        const schedulerScopes = mcpLedgerScopes(mcpWireInput);
+        const ledgerEffectContract = mcpLedgerEffectContract(
+          localToolDescriptor,
+          hostToolPolicy,
+        );
+        const schedulerEffectContract = ledgerEffectContract.trusted
+          ? createHostOwnedMcpEffectContract(ledgerEffectContract)
+          : ledgerEffectContract;
+        const scheduler =
+          mcpConflictScheduler || directMcpConflictScheduler(mcpClient);
+        let schedulerLease;
         try {
-          const result = await mcpClient.callTool(
-            localToolExecutor.serverName,
-            localToolExecutor.toolName,
-            args || {},
+          schedulerLease = await scheduler.acquire(
+            {
+              effectContract: schedulerEffectContract,
+              ...schedulerScopes,
+            },
+            { signal },
           );
-          if (result && typeof result === "object") {
-            return attachDescriptor(result);
-          }
-          return attachDescriptor({ result });
         } catch (err) {
           return attachDescriptor({
-            error: `MCP tool execution failed: ${err.message}`,
+            error: `MCP tool blocked by the effect conflict scheduler: ${err.message}`,
+            policy: {
+              decision: "blocked",
+              via: "mcp-conflict-scheduler",
+              code: err?.code || null,
+            },
           });
         }
+
+        try {
+          const ledger = mcpCallLedger || createMcpCallLedger();
+          let ledgerTicket;
+          try {
+            ledgerTicket = await ledger.begin({
+              sessionId,
+              turnId,
+              toolName: localToolExecutor.toolName,
+              serverName: localToolExecutor.serverName,
+              input: mcpWireInput,
+              effectContract: ledgerEffectContract,
+              ...schedulerScopes,
+            });
+          } catch (err) {
+            return attachDescriptor({
+              error: `MCP tool blocked because its call ledger prewrite failed: ${err.message}`,
+              policy: {
+                decision: "blocked",
+                via: "mcp-ledger-prewrite",
+                code: err?.code || null,
+                ledgerId: err?.ledgerId || null,
+                effect: err?.effect || null,
+                blockMode: err?.blockMode || null,
+              },
+            });
+          }
+
+          const transportFailure = async (callError) => {
+            if (mcpTransportOutcomeIsUnsafe(ledgerEffectContract)) {
+              return attachDescriptor(
+                mcpOutcomeUnknownPayload(ledger, ledgerTicket, {
+                  phase: "call",
+                  reasonCode: MCP_TRANSPORT_OUTCOME_UNKNOWN_CODE,
+                }),
+              );
+            }
+            try {
+              await ledgerTicket.settle({
+                status: "failed",
+                error: callError,
+              });
+            } catch (ledgerError) {
+              return attachDescriptor(
+                mcpOutcomeUnknownPayload(ledger, ledgerTicket, {
+                  phase: "settled",
+                  reasonCode: safeMcpErrorCode(
+                    ledgerError,
+                    "CC_MCP_LEDGER_SETTLE_FAILED",
+                  ),
+                }),
+              );
+            }
+            return attachDescriptor({
+              error: `MCP tool execution failed: ${safeMcpErrorMessage(callError)}`,
+              mcpLedgerId: safeMcpProperty(ledgerTicket, "ledgerId") || null,
+            });
+          };
+
+          let pendingResult;
+          try {
+            pendingResult = Reflect.apply(mcpClient.callTool, mcpClient, [
+              localToolExecutor.serverName,
+              localToolExecutor.toolName,
+              mcpWireInput,
+            ]);
+          } catch (callError) {
+            return await transportFailure(callError);
+          }
+
+          let result;
+          if (
+            pendingResult !== null &&
+            (typeof pendingResult === "object" ||
+              typeof pendingResult === "function")
+          ) {
+            if (isProxy(pendingResult)) {
+              return attachDescriptor(
+                mcpOutcomeUnknownPayload(ledger, ledgerTicket, {
+                  phase: "result",
+                  reasonCode: MCP_PROTOCOL_RESULT_INVALID_CODE,
+                }),
+              );
+            }
+
+            let nativePromise;
+            try {
+              nativePromise = pendingResult instanceof Promise;
+            } catch (inspectionError) {
+              return attachDescriptor(
+                mcpOutcomeUnknownPayload(ledger, ledgerTicket, {
+                  phase: "result",
+                  reasonCode: safeMcpErrorCode(
+                    invalidMcpProtocolResult(inspectionError),
+                    MCP_PROTOCOL_RESULT_INVALID_CODE,
+                  ),
+                }),
+              );
+            }
+
+            if (nativePromise) {
+              try {
+                result = await pendingResult;
+              } catch (callError) {
+                return await transportFailure(callError);
+              }
+            } else {
+              let then;
+              try {
+                then = Reflect.get(pendingResult, "then", pendingResult);
+              } catch (inspectionError) {
+                return attachDescriptor(
+                  mcpOutcomeUnknownPayload(ledger, ledgerTicket, {
+                    phase: "result",
+                    reasonCode: safeMcpErrorCode(
+                      invalidMcpProtocolResult(inspectionError),
+                      MCP_PROTOCOL_RESULT_INVALID_CODE,
+                    ),
+                  }),
+                );
+              }
+              if (typeof then === "function") {
+                try {
+                  result = await new Promise((resolve, reject) => {
+                    try {
+                      Reflect.apply(then, pendingResult, [resolve, reject]);
+                    } catch (thenError) {
+                      reject(thenError);
+                    }
+                  });
+                } catch (thenError) {
+                  return attachDescriptor(
+                    mcpOutcomeUnknownPayload(ledger, ledgerTicket, {
+                      phase: "result",
+                      reasonCode: safeMcpErrorCode(
+                        invalidMcpProtocolResult(thenError),
+                        MCP_PROTOCOL_RESULT_INVALID_CODE,
+                      ),
+                    }),
+                  );
+                }
+              } else {
+                result = pendingResult;
+              }
+            }
+          } else {
+            result = pendingResult;
+          }
+
+          let protocolError;
+          try {
+            if (
+              result !== null &&
+              (typeof result === "object" || typeof result === "function") &&
+              isProxy(result)
+            ) {
+              throw invalidMcpProtocolResult();
+            }
+            protocolError = result?.isError === true;
+          } catch (inspectionError) {
+            return attachDescriptor(
+              mcpOutcomeUnknownPayload(ledger, ledgerTicket, {
+                phase: "result",
+                reasonCode: safeMcpErrorCode(
+                  invalidMcpProtocolResult(inspectionError),
+                  MCP_PROTOCOL_RESULT_INVALID_CODE,
+                ),
+              }),
+            );
+          }
+
+          try {
+            await ledgerTicket.settle(
+              protocolError
+                ? {
+                    status: "failed",
+                    output: result,
+                    error: new Error("MCP server returned isError=true"),
+                  }
+                : { status: "completed", output: result },
+            );
+          } catch (ledgerError) {
+            return attachDescriptor(
+              mcpOutcomeUnknownPayload(ledger, ledgerTicket, {
+                phase: "settled",
+                reasonCode: safeMcpErrorCode(
+                  ledgerError,
+                  "CC_MCP_LEDGER_SETTLE_FAILED",
+                ),
+              }),
+            );
+          }
+
+          const mcpLedgerId = safeMcpProperty(ledgerTicket, "ledgerId") || null;
+          try {
+            if (result && typeof result === "object") {
+              return attachDescriptor({ ...result, mcpLedgerId });
+            }
+            return attachDescriptor({ result, mcpLedgerId });
+          } catch (projectionError) {
+            return attachDescriptor({
+              error:
+                "MCP tool completed, but its result could not be projected safely; do not retry automatically.",
+              code: MCP_RESULT_PROJECTION_FAILED_CODE,
+              retryable: false,
+              mcpLedgerId,
+              mcpLedgerIncident: {
+                phase: "result",
+                code: safeMcpErrorCode(
+                  projectionError,
+                  MCP_RESULT_PROJECTION_FAILED_CODE,
+                ),
+              },
+            });
+          }
+        } finally {
+          schedulerLease.release();
+        }
       }
 
       if (
@@ -6190,11 +6879,41 @@ function* _drainSubAgentUsage(sink) {
       provider: u?.provider ?? null,
       model: u?.model ?? null,
       usage: u?.usage || {},
+      ...(u?.source ? { source: u.source } : {}),
       attribution: u?.attribution || null,
     };
   }
 }
 
+/**
+ * Build the bounded, deterministic parent-to-child handoff used when callers
+ * do not supply explicit context. Keeping the same nine-field schema as
+ * semantic compaction prevents decisions, tests, and unresolved side effects
+ * from disappearing merely because work crosses a sub-agent boundary.
+ */
+export function buildSubAgentHandoffContext(messages) {
+  if (!Array.isArray(messages)) return null;
+  const canonicalMessages = projectCanonicalResumeMessages(messages);
+  const hasContent = canonicalMessages.some((message) => {
+    if (!message || !["user", "assistant", "tool"].includes(message.role)) {
+      return false;
+    }
+    if (typeof message.content === "string") {
+      return message.content.trim().length > 0;
+    }
+    return message.content != null;
+  });
+  if (!hasContent) return null;
+
+  const handoff = buildExtractiveHandoff(canonicalMessages, {
+    maxContentChars: 6000,
+    maxItemsPerField: 6,
+    maxItemChars: 500,
+    maxFallbackSourceChars: 16000,
+  });
+  return `[Structured parent handoff v1]\n${formatStructuredHandoff(handoff)}`;
+}
+
 async function _executeSpawnSubAgent(args, ctx) {
   // Nesting cap: refuse before any context/registry work.
   const currentDepth = ctx.subAgentDepth || 0;
@@ -6218,8 +6937,10 @@ async function _executeSpawnSubAgent(args, ctx) {
         hardChildrenCap: ctx.subAgentBudget?.max ?? MAX_SUB_AGENTS_PER_RUN,
       });
       if (!recur.ok) return { error: `spawn_sub_agent: ${recur.reason}` };
-    } catch {
-      /* contract module unavailable — hard caps above still apply */
+    } catch (err) {
+      return {
+        error: `spawn_sub_agent: parent contract enforcement failed closed (${err.message}).`,
+      };
     }
   }
   // Breadth cap: a shared counter (one object for the whole tree) bounds the
@@ -6242,9 +6963,20 @@ async function _executeSpawnSubAgent(args, ctx) {
     role,
     task,
     context: inheritedContext,
+    contextMode,
     tools: explicitTools,
     profile: profileName,
   } = args;
+  // Compatibility bridge for callers that used the original overloaded
+  // `context: fresh|fork` authority spelling. An explicit `contextMode` always
+  // wins and makes `context` unambiguously prompt text.
+  const legacyContextMode =
+    contextMode == null &&
+    (inheritedContext === "fresh" || inheritedContext === "fork")
+      ? inheritedContext
+      : null;
+  if (legacyContextMode) inheritedContext = null;
+  const requestedContextMode = contextMode ?? legacyContextMode;
   // Extended sub-agent contract (gap 2026-07-11 P1): per-spawn deny-list,
   // iteration cap and worktree isolation — spawn args win over the agent
   // file's frontmatter defaults.
@@ -6311,7 +7043,7 @@ async function _executeSpawnSubAgent(args, ctx) {
   // effort, context inheritance); this child's contract becomes the ceiling for
   // ITS own nested spawns (threaded via SubAgentContext.subAgentContract).
   let effectiveContract = null;
-  let explicitContext = null;
+  let explicitContextMode = null;
   let skillAllowlist = null;
   // MCP-server + hook allow-lists for child INHERITANCE. Default `[]` = inherit
   // NONE, which equals today's behavior (a spawned child gets zero MCP tools /
@@ -6326,10 +7058,23 @@ async function _executeSpawnSubAgent(args, ctx) {
   // = byte-identical.
   let permModeDriven = false;
   try {
-    const { resolveSubagentContract, normalizeSubagentContract } =
-      await import("../lib/subagent-contract.js");
-    const spawnContract = normalizeSubagentContract(args);
-    explicitContext = spawnContract.context ?? mdContract?.context ?? null;
+    const {
+      resolveSubagentContract,
+      normalizeSubagentContract,
+      assertValidSubagentContract,
+    } = await import("../lib/subagent-contract.js");
+    // `context` predates the authority contract and remains arbitrary prompt
+    // text except for the narrow legacy spelling handled above. Map the
+    // separate contextMode field onto the contract's canonical `context` key.
+    const authorityArgs = { ...args };
+    delete authorityArgs.context;
+    delete authorityArgs.contextMode;
+    if (requestedContextMode != null) {
+      authorityArgs.context = requestedContextMode;
+    }
+    assertValidSubagentContract(authorityArgs);
+    const spawnContract = normalizeSubagentContract(authorityArgs);
+    explicitContextMode = spawnContract.context ?? mdContract?.context ?? null;
     effectiveContract = resolveSubagentContract({
       parent: ctx.subAgentContract || {},
       definition: mdContract,
@@ -6349,7 +7094,7 @@ async function _executeSpawnSubAgent(args, ctx) {
     const skillsDriven =
       spawnContract.skills != null ||
       mdContract?.skills != null ||
-      explicitContext != null;
+      explicitContextMode != null;
     skillAllowlist = skillsDriven ? (effectiveContract.skills ?? null) : null;
     // MCP/hooks work the OTHER way from skills: their pre-inheritance default is
     // "none", so the silent-`fresh`→[] resolution IS the safe current behavior —
@@ -6357,12 +7102,10 @@ async function _executeSpawnSubAgent(args, ctx) {
     // into inheriting the corresponding parent capabilities.
     mcpAllow = effectiveContract.mcpServers ?? null;
     hookAllow = effectiveContract.hooks ?? null;
-  } catch {
-    effectiveContract = null; // contract resolution is best-effort
-    skillAllowlist = null;
-    mcpAllow = []; // inherit no MCP / hooks when resolution fails
-    hookAllow = [];
-    permModeDriven = false; // no gate when resolution fails
+  } catch (err) {
+    return {
+      error: `spawn_sub_agent: authority contract resolution failed closed (${err.message}).`,
+    };
   }
 
   // Filter the parent loop's live MCP plumbing + settings hooks down to what the
@@ -6383,9 +7126,10 @@ async function _executeSpawnSubAgent(args, ctx) {
       mcpAllow,
     );
     inheritedHooks = filterInheritedHooks(ctx.settingsHooks || null, hookAllow);
-  } catch {
-    inheritedMcp = null; // inheritance is best-effort; never break the spawn
-    inheritedHooks = null;
+  } catch (err) {
+    return {
+      error: `spawn_sub_agent: capability inheritance failed closed (${err.message}).`,
+    };
   }
 
   // Memory INHERITANCE (contract `memory` boolean, tighten-only across depth):
@@ -6412,8 +7156,10 @@ async function _executeSpawnSubAgent(args, ctx) {
         available: isGitRepo(ctx.cwd),
       });
       if (!iso.ok) return { error: `spawn_sub_agent: ${iso.reason}` };
-    } catch {
-      /* helper unavailable — sub-agent-context.js still fails closed at run() */
+    } catch (err) {
+      return {
+        error: `spawn_sub_agent: isolation enforcement failed closed (${err.message}).`,
+      };
     }
   }
 
@@ -6430,8 +7176,10 @@ async function _executeSpawnSubAgent(args, ctx) {
           error: `Unknown sub-agent profile: "${profileName}". Valid: explorer|executor|design`,
         };
       }
-    } catch (_err) {
-      // profile module optional — proceed without
+    } catch (err) {
+      return {
+        error: `spawn_sub_agent: requested profile resolution failed closed (${err.message}).`,
+      };
     }
   }
 
@@ -6453,6 +7201,16 @@ async function _executeSpawnSubAgent(args, ctx) {
     allowedTools = base.filter((t) => !deny.has(t));
   }
 
+  // A child can never regain a tool omitted from the parent's effective schema.
+  // `[]` remains deny-all all the way into the child's execution-time fence.
+  if (Array.isArray(ctx.effectiveAllowedToolNames)) {
+    const parentCeiling = new Set(ctx.effectiveAllowedToolNames);
+    const requested = Array.isArray(allowedTools)
+      ? allowedTools
+      : [...parentCeiling];
+    allowedTools = requested.filter((tool) => parentCeiling.has(tool));
+  }
+
   // permissionMode enforcement into the child gate. Reuses the runner's own
   // resolvers (single-sourced, no drift); best-effort so it never breaks a spawn.
   //  • `plan` → clamp to the read-only tool set (same rule as resolveEnabledTools),
@@ -6501,27 +7259,23 @@ async function _executeSpawnSubAgent(args, ctx) {
           defaultPolicy: perm.sessionPolicy,
         });
       }
-    } catch {
-      // Enforcement is best-effort — never break the spawn.
+    } catch (err) {
+      return {
+        error: `spawn_sub_agent: permission-mode enforcement failed closed (${err.message}).`,
+      };
     }
   }
 
-  // Auto-condense parent context if caller didn't provide explicit context.
-  // An explicit `context: fresh` contract suppresses this inheritance (the
-  // child starts clean); `fork` / unset keep the existing auto-condense.
+  // Build a structured parent handoff if the caller did not provide explicit
+  // An explicit `contextMode: fresh` contract suppresses this inheritance (the
+  // child starts clean); `fork` / unset keep deterministic auto-inheritance.
   let resolvedContext = inheritedContext || null;
   if (
     !resolvedContext &&
-    explicitContext !== "fresh" &&
+    explicitContextMode !== "fresh" &&
     Array.isArray(ctx.parentMessages)
   ) {
-    const recentMsgs = ctx.parentMessages
-      .filter((m) => m.role === "assistant" && typeof m.content === "string")
-      .slice(-3)
-      .map((m) => m.content.substring(0, 200));
-    if (recentMsgs.length > 0) {
-      resolvedContext = recentMsgs.join("\n---\n");
-    }
+    resolvedContext = buildSubAgentHandoffContext(ctx.parentMessages);
   }
 
   // Link child to parent session so registry-scoped queries and
@@ -6557,8 +7311,10 @@ async function _executeSpawnSubAgent(args, ctx) {
           ? `${resolvedContext}\n---\n${injected}`
           : injected;
       }
-    } catch (_err) {
-      // SubagentStart hooks are best-effort — never break the spawn.
+    } catch (err) {
+      return {
+        error: `spawn_sub_agent: SubagentStart authority hook failed closed (${err.message}).`,
+      };
     }
   }
 
@@ -6592,6 +7348,7 @@ async function _executeSpawnSubAgent(args, ctx) {
                   provider: u?.provider ?? null,
                   model: u?.model ?? null,
                   usage: u?.usage || null,
+                  ...(u?.source ? { source: u.source } : {}),
                   attribution: {
                     origin: "subagent",
                     subagentId: subCtxRef?.id || null,
@@ -6626,11 +7383,23 @@ async function _executeSpawnSubAgent(args, ctx) {
       if (sparse) wtOpts.sparsePaths = sparse;
       if (symlink != null) wtOpts.symlinkDirectories = symlink;
       if (Object.keys(wtOpts).length) subWorktreeOptions = wtOpts;
-    } catch {
-      subWorktreeOptions = null; // best-effort → full checkout on any error
+    } catch (err) {
+      return {
+        error: `spawn_sub_agent: worktree scope resolution failed closed (${err.message}).`,
+      };
     }
   }
 
+  // Preserve host deny/policy metadata, but do not implicitly inherit hosted
+  // external definitions. MCP/host capabilities enter the child only through
+  // the explicit contract-filtered plumbing above.
+  const childHostManagedToolPolicy = ctx.hostManagedToolPolicy
+    ? { ...ctx.hostManagedToolPolicy, toolDefinitions: [] }
+    : null;
+  // A parent gate is already an authority ceiling. Prefer it over a newly
+  // derived child gate so an explicit child mode can never relax the parent.
+  const effectiveChildApprovalGate = ctx.approvalGate || childApprovalGate;
+
   const subCtx = SubAgentContext.create({
     role,
     task,
@@ -6639,7 +7408,7 @@ async function _executeSpawnSubAgent(args, ctx) {
     // and THIS run's id as parent_id on every settings-hook payload it fires.
     hookParentTraceId: ctx.hookTraceId || null,
     inheritedContext: resolvedContext,
-    allowedTools: allowedTools || null,
+    allowedTools: allowedTools ?? null,
     cwd: ctx.cwd,
     profile: profile || null,
     llmOptions: subLlmOptions,
@@ -6647,6 +7416,7 @@ async function _executeSpawnSubAgent(args, ctx) {
     // 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).
     subAgentBudget: ctx.subAgentBudget || null,
+    ...(ctx.sessionBudget ? { sessionBudget: ctx.sessionBudget } : {}),
     onUsage,
     // Extended contract (gap 2026-07-11): per-agent iteration cap + opt-in
     // worktree isolation. undefined keeps the profile/flag defaults intact.
@@ -6674,6 +7444,10 @@ async function _executeSpawnSubAgent(args, ctx) {
           externalToolDescriptors: inheritedMcp.externalToolDescriptors,
           externalToolExecutors: inheritedMcp.externalToolExecutors,
           mcpClient: inheritedMcp.mcpClient,
+          ...(ctx.mcpCallLedger ? { mcpCallLedger: ctx.mcpCallLedger } : {}),
+          ...(ctx.mcpConflictScheduler
+            ? { mcpConflictScheduler: ctx.mcpConflictScheduler }
+            : {}),
         }
       : {}),
     ...(inheritedHooks ? { settingsHooks: inheritedHooks } : {}),
@@ -6696,7 +7470,27 @@ async function _executeSpawnSubAgent(args, ctx) {
     // permissionMode ApprovalGate (2026-07-13): a dedicated confirmer-less gate
     // seeded with the mode's tier gates the child's run_shell / browser_act;
     // absent (ungated) for a plain default spawn = byte-identical.
-    ...(childApprovalGate ? { approvalGate: childApprovalGate } : {}),
+    ...(effectiveChildApprovalGate
+      ? { approvalGate: effectiveChildApprovalGate }
+      : {}),
+    // Parent execution authority is inherited as a tighten-only bundle and is
+    // re-enforced by the child's executeTool path on every provider tool call.
+    ...(ctx.permissionRules ? { permissionRules: ctx.permissionRules } : {}),
+    ...(childHostManagedToolPolicy
+      ? { hostManagedToolPolicy: childHostManagedToolPolicy }
+      : {}),
+    ...(ctx.planManager ? { planManager: ctx.planManager } : {}),
+    ...(ctx.sandbox ? { sandbox: ctx.sandbox } : {}),
+    ...(Array.isArray(ctx.additionalDirectories)
+      ? { additionalDirectories: [...ctx.additionalDirectories] }
+      : {}),
+    ...(ctx.shellPolicyOverrides
+      ? { shellPolicyOverrides: ctx.shellPolicyOverrides }
+      : {}),
+    ...(ctx.classifyAllShell ? { classifyAllShell: true } : {}),
+    ...(ctx.unattendedActionPolicy
+      ? { unattendedActionPolicy: ctx.unattendedActionPolicy }
+      : {}),
     ...(ctx.toolAdmission ? { toolAdmission: ctx.toolAdmission } : {}),
   });
   subCtxRef = subCtx;
@@ -6777,7 +7571,7 @@ async function _executeSpawnSubAgent(args, ctx) {
     emit("sub-agent.started", {
       task: subCtx.task,
       background: true,
-      allowedTools: allowedTools || null,
+      allowedTools: allowedTools ?? null,
       maxIterations: subCtx.maxIterations,
       createdAt: subCtx.createdAt,
     });
@@ -6854,7 +7648,7 @@ async function _executeSpawnSubAgent(args, ctx) {
 
     emit("sub-agent.started", {
       task: subCtx.task,
-      allowedTools: allowedTools || null,
+      allowedTools: allowedTools ?? null,
       maxIterations: subCtx.maxIterations,
       createdAt: subCtx.createdAt,
     });
@@ -6870,6 +7664,24 @@ async function _executeSpawnSubAgent(args, ctx) {
       }
     }
 
+    if (result?.budgetReason) {
+      emit("sub-agent.failed", {
+        status: subCtx.status,
+        error: result.summary,
+        budgetReason: result.budgetReason,
+        completedAt: subCtx.completedAt,
+      });
+      return {
+        error: result.summary,
+        code: "ERR_SESSION_RESOURCE_BUDGET",
+        budgetReason: result.budgetReason,
+        subAgentId: subCtx.id,
+        role: subCtx.role,
+        parentSessionId,
+        childBinding: subCtx.recoveryBinding(result),
+      };
+    }
+
     emit("sub-agent.completed", {
       status: subCtx.status,
       summary: result.summary,
@@ -6924,6 +7736,26 @@ async function _executeSpawnSubAgent(args, ctx) {
 
 // ─── LLM chat with tools ─────────────────────────────────────────────────
 
+function getEffectiveToolDefinitions(options = {}) {
+  const persona = _loadProjectPersona(options.cwd);
+  // Merge every deny source before both schema projection and execution-time
+  // enforcement. Keeping this in one helper prevents those two fences from
+  // drifting apart.
+  const mergedDisabledTools = [
+    ...(Array.isArray(persona?.toolsDisabled) ? persona.toolsDisabled : []),
+    ...(Array.isArray(options.disabledTools) ? options.disabledTools : []),
+  ];
+  return getAgentToolDefinitions({
+    names: options.enabledToolNames,
+    disabledTools: mergedDisabledTools,
+    exactToolNames: options.exactToolNames === true,
+    extraTools: [
+      ...(options.hostManagedToolPolicy?.toolDefinitions || []),
+      ...(options.extraToolDefinitions || []),
+    ],
+  });
+}
+
 /**
  * Send a chat completion request with tool definitions.
  * Supports 8 providers: ollama, anthropic, openai, deepseek, dashscope, gemini, mistral, volcengine
@@ -6942,22 +7774,7 @@ export async function chatWithTools(rawMessages, options) {
     signal,
   } = options;
 
-  const persona = _loadProjectPersona(options.cwd);
-  // Merge the project-persona deny-list with any caller-supplied deny-list
-  // (e.g. headless `--disallowed-tools`). Without this merge the caller's
-  // deny-list is silently dropped and the tool stays callable.
-  const mergedDisabledTools = [
-    ...(Array.isArray(persona?.toolsDisabled) ? persona.toolsDisabled : []),
-    ...(Array.isArray(options.disabledTools) ? options.disabledTools : []),
-  ];
-  const tools = getAgentToolDefinitions({
-    names: options.enabledToolNames,
-    disabledTools: mergedDisabledTools,
-    extraTools: [
-      ...(options.hostManagedToolPolicy?.toolDefinitions || []),
-      ...(options.extraToolDefinitions || []),
-    ],
-  });
+  const tools = getEffectiveToolDefinitions(options);
 
   const lastUserMsg = [...rawMessages].reverse().find((m) => m.role === "user");
   const messages = ce
@@ -6986,7 +7803,14 @@ export async function chatWithTools(rawMessages, options) {
         () =>
           _chatOllamaStreaming(
             apiUrl,
-            { model, messages: ollamaMessages, tools },
+            {
+              model,
+              messages: ollamaMessages,
+              tools,
+              ...(options.maxOutputTokens
+                ? { options: { num_predict: options.maxOutputTokens } }
+                : {}),
+            },
             options.onToken,
             signal,
             options.onStall,
@@ -7013,6 +7837,9 @@ export async function chatWithTools(rawMessages, options) {
         messages: ollamaMessages,
         tools,
         stream: false,
+        ...(options.maxOutputTokens
+          ? { options: { num_predict: options.maxOutputTokens } }
+          : {}),
       }),
     });
     if (!response.ok) {
@@ -7071,7 +7898,9 @@ export async function chatWithTools(rawMessages, options) {
     );
     const body = {
       model: effModel,
-      max_tokens: anthropicMaxTokens || 8192,
+      max_tokens: options.maxOutputTokens
+        ? Math.min(anthropicMaxTokens || 8192, options.maxOutputTokens)
+        : anthropicMaxTokens || 8192,
       // Convert cc's internal OpenAI-shaped history (role:"tool" results,
       // assistant tool_calls[]) into Anthropic content blocks. Without this,
       // multi-turn tool use 400s on turn 2 (Anthropic rejects role:"tool" and
@@ -7230,6 +8059,9 @@ export async function chatWithTools(rawMessages, options) {
             tools,
             stream: true,
             stream_options: { include_usage: true },
+            ...(options.maxOutputTokens
+              ? { max_tokens: options.maxOutputTokens }
+              : {}),
           },
           key,
           options.onToken,
@@ -7262,6 +8094,9 @@ export async function chatWithTools(rawMessages, options) {
       model: model || defaultModels[provider] || "gpt-4o-mini",
       messages,
       tools,
+      ...(options.maxOutputTokens
+        ? { max_tokens: options.maxOutputTokens }
+        : {}),
     }),
   });
 
@@ -8267,9 +9102,45 @@ async function _getAutoCompactor(options) {
     if (feature("PROMPT_COMPRESSOR")) {
       const { PromptCompressor } =
         await import("../harness/prompt-compressor.js");
+      const llmQuery =
+        typeof options.compactionLlmQuery === "function"
+          ? options.compactionLlmQuery
+          : options.chatFn
+            ? null
+            : async (prompt) => {
+                const maxOutputTokens = Math.min(
+                  4096,
+                  Math.max(
+                    256,
+                    Number(options.compactionMaxOutputTokens) || 2048,
+                  ),
+                );
+                const response = await chatWithTools(
+                  [{ role: "user", content: prompt }],
+                  {
+                    ...options,
+                    contextEngine: null,
+                    enabledToolNames: [],
+                    extraToolDefinitions: [],
+                    hostManagedToolPolicy: null,
+                    onToken: undefined,
+                    onStall: undefined,
+                    onStreamRetry: undefined,
+                    maxOutputTokens,
+                  },
+                );
+                return {
+                  summary: response?.message?.content || "",
+                  usage: response?.usage || null,
+                  provider: options.provider || null,
+                  model: options.model || null,
+                };
+              };
       compressor = new PromptCompressor({
         model: options.model,
         provider: options.provider,
+        llmQuery,
+        summaryInputMaxChars: options.compactionInputMaxChars,
       });
     }
   } catch {
@@ -8283,6 +9154,21 @@ async function _getAutoCompactor(options) {
   return compressor;
 }
 
+function _compactionTokenUsage(stats) {
+  const summaryUsage = stats?.summaryUsage;
+  if (!summaryUsage || typeof summaryUsage !== "object") return null;
+  const tokenCount = (value) => {
+    const number = Number(value);
+    return Number.isFinite(number) && number > 0 ? Math.trunc(number) : 0;
+  };
+  return {
+    input_tokens: tokenCount(summaryUsage.inputTokens),
+    output_tokens: tokenCount(summaryUsage.outputTokens),
+    cache_read_input_tokens: tokenCount(summaryUsage.cacheReadTokens),
+    cache_creation_input_tokens: tokenCount(summaryUsage.cacheCreationTokens),
+  };
+}
+
 /**
  * Run `fn` inside an OpenTelemetry span when `options.recorder` is attached,
  * else run it bare (zero overhead on the un-instrumented path). `onResult`
@@ -8390,6 +9276,15 @@ export async function* agentLoop(messages, options) {
     options.runId ||
     `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 
+  const effectiveAllowedToolNames = Object.freeze(
+    getEffectiveToolDefinitions(options).map((tool) => tool.function.name),
+  );
+  const mcpCallLedger =
+    options.mcpCallLedger ||
+    createMcpCallLedger({ sink: options.mcpLedgerSink || null });
+  const mcpConflictScheduler =
+    options.mcpConflictScheduler || createMcpConflictScheduler();
+
   const toolContext = {
     hookDb: options.hookDb || null,
     skillLoader: options.skillLoader || _defaultSkillLoader,
@@ -8404,6 +9299,7 @@ export async function* agentLoop(messages, options) {
     // unrestricted; [] = none; a list restricts run_skill/list_skills to those
     // ids/dirNames. Set by the spawn path from the resolved subagent contract.
     skillAllowlist: options.skillAllowlist ?? null,
+    effectiveAllowedToolNames,
     cwd: options.cwd || process.cwd(),
     planManager: options.planManager || null,
     sessionId: options.sessionId || null,
@@ -8425,6 +9321,14 @@ export async function* agentLoop(messages, options) {
     // contract's mcpServers allow-list). Otherwise consumed only at agentLoop.
     extraToolDefinitions: options.extraToolDefinitions || null,
     mcpClient: options.mcpClient || null,
+    mcpHostClient: options.mcpHostClient || options.mcpClient || null,
+    mcpCallLedger,
+    mcpConflictScheduler,
+    // 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.
+    subtreeInstructionScope:
+      options.subtreeInstructionScope || options.sessionId || Symbol(runId),
     // Parent memory source — a spawn can inherit the parent's hierarchical
     // memory DB into the child ONLY when the resolved contract grants memory
     // (context:fork from a memory-bearing parent, or explicit memory:true).
@@ -8482,6 +9386,10 @@ export async function* agentLoop(messages, options) {
       spawned: 0,
       max: MAX_SUB_AGENTS_PER_RUN,
     },
+    // Optional local adapter for a host-created SessionResourceBudget. The
+    // CLI root does not create one yet; when supplied, every nested child sees
+    // the same object and cannot reset concurrency/spawn/depth totals.
+    sessionBudget: options.sessionBudget || null,
     // This loop's EFFECTIVE subagent contract (set when this loop IS a spawned
     // sub-agent). Threaded so a nested spawn_sub_agent sees it as the parent
     // ceiling (tighten-only). null at the top level (no ceiling).
@@ -8584,7 +9492,7 @@ export async function* agentLoop(messages, options) {
         // line) when provided; otherwise fall back to a clear stderr notice.
         const message =
           reason === "env-key"
-            ? `"${from}" 鉴权失败，已临时切换到不同厂商 "${to}"（请检查 ${from} 的 API key：cc config set llm.apiKey …）。`
+            ? `"${from}" 鉴权失败，已临时切换到不同厂商 "${to}"（请检查 ${from} 的 API key：cc config set-secret llm.apiKey）。`
             : reason === "model-mismatch"
               ? `模型 "${fromModel}" 不属于 ${from}，已改用其默认模型 "${toModel}"（用 cc config set llm.model 设置正确的 ${from} 模型）。`
               : `provider 配置与 baseUrl 不一致，已按 baseUrl 切换到 "${to}"。`;
@@ -8765,6 +9673,16 @@ export async function* agentLoop(messages, options) {
                   preserveToolPairs: true,
                   ...pinOpts,
                 });
+          const compactionUsage = _compactionTokenUsage(stats);
+          if (stats.degraded === true) {
+            yield {
+              type: "compaction-degraded",
+              runId,
+              reason: stats.degradedReason || "semantic-summary-degraded",
+              summaryMode: stats.summaryMode || "extractive-fallback",
+              stats,
+            };
+          }
           if (stats.saved > 0 && compacted.length < messages.length) {
             messages.splice(0, messages.length, ...compacted);
             // Persist the compaction so a later --resume rebuilds from the
@@ -8806,10 +9724,31 @@ export async function* agentLoop(messages, options) {
             });
             yield { type: "compaction", stats, runId };
           }
+          if (compactionUsage) {
+            // PromptCompressor calls the provider directly, outside the main
+            // chat request. Apply/persist the resulting compaction and surface
+            // any degraded fallback before yielding billable usage: a
+            // headless consumer may stop the generator as soon as its cost cap
+            // is exceeded. Usage still arrives exactly once and before the
+            // next model call, without entering the normal response path.
+            yield {
+              type: "token-usage",
+              provider: stats.summaryProvider || options.provider || null,
+              model: stats.summaryModel || options.model || null,
+              usage: compactionUsage,
+              source: "semantic-compaction",
+              runId,
+            };
+          }
         }
       } catch (_e) {
         if (isAbortError(_e) || signal?.aborted) throw _e;
-        // Compaction is best-effort — proceed with the uncompacted messages.
+        yield {
+          type: "compaction-degraded",
+          runId,
+          reason: `compaction_failed:${_e?.message || String(_e)}`,
+          summaryMode: "none",
+        };
       }
     }