chainlesschain 0.166.10 → 0.166.13

package/src/runtime/agent-core.js

@@ -24,7 +24,6 @@ import sharedCodingAgentPolicy from "./coding-agent-policy.cjs";
 import sharedShellPolicy from "./coding-agent-shell-policy.cjs";
 import sharedPermissionRules from "../lib/permission-rules.cjs";
 import sharedSettingsHooks from "../lib/settings-hooks.cjs";
-import sharedHookRunner from "../lib/hook-runner.js";
 import sharedHookEvents from "../lib/settings-hook-events.js";
 import { mergeProviderOptions } from "../lib/provider-options.js";
 import { applyCredentialProxy } from "../lib/credential-proxy.js";
@@ -48,7 +47,6 @@ import {
   debitSkillPromptBudget,
   resolveSkillLimits,
 } from "../lib/skill-budget.js";
-import { executeHooks, HookEvents } from "../lib/hook-manager.js";
 import { detectPython } from "../lib/cli-anything-bridge.js";
 import { findProjectRoot, loadProjectConfig } from "../lib/project-detector.js";
 import { SubAgentContext } from "../lib/sub-agent-context.js";
@@ -179,14 +177,8 @@ const { isDangerousGitCommand, isReadOnlyGitCommand, normalizeGitCommand } =
   sharedCodingAgentPolicy;
 const { evaluateShellCommandPolicy } = sharedShellPolicy;
 const { evaluatePermissionRules } = sharedPermissionRules;
-const { collectHooks, umbrellaFor } = sharedSettingsHooks;
-const { runHooks: runCommandHooks } = sharedHookRunner;
-const {
-  runObserveHooks,
-  aggregateContext,
-  partitionAsyncHooks,
-  withDeliveryId,
-} = sharedHookEvents;
+const { umbrellaFor } = sharedSettingsHooks;
+const { runObserveHooks, aggregateContext } = sharedHookEvents;
 
 const searchProcessRunner = broker.execSync.bind(broker);
 const runCodeProcessRunner = broker.execFileSync.bind(broker);
@@ -764,156 +756,6 @@ function _resolveShellTimeout(raw) {
   return Math.min(Math.floor(n), MAX_SHELL_TIMEOUT_MS);
 }
 
-/**
- * Run settings.json `PreToolUse` hooks (decision-capable). DB hooks are handled
- * separately + stay observe-only. A `block` decision stops the tool; an `ask`
- * routes to the confirmer (headless without one falls closed). spawnSync is
- * synchronous but each hook is timeout-capped.
- * @returns {Promise<{blocked:boolean, reason?:string, hook?:string}>}
- */
-async function runSettingsPreToolUseHooks(name, args, context, cwd) {
-  const matched = collectHooks(context.settingsHooks, "PreToolUse", name);
-  if (!matched || matched.length === 0) return { blocked: false };
-  // Unified-bus envelope (P2): stamps event_id + threads trace_id (this run) /
-  // parent_id (spawning run) from the loop context. Additive fields — a hook
-  // that ignores them is unaffected; absent context omits them entirely.
-  const payload = withDeliveryId(
-    "PreToolUse",
-    {
-      hook_event_name: "PreToolUse",
-      tool_name: umbrellaFor(name),
-      raw_tool_name: name,
-      tool_input: args,
-      cwd,
-      session_id: context.sessionId || null,
-    },
-    {
-      sessionId: context.sessionId || null,
-      traceId: context.hookTraceId || null,
-      parentId: context.hookParentId || null,
-    },
-  );
-  // 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 };
-  }
-  if (outcome.decision === "ask") {
-    // File edits in an interactive session with an IDE bridge: route the ask
-    // through the editor's openDiff review (same machinery as settings ask —
-    // accepted means the IDE wrote the file, so the caller must skip
-    // execution; see tryIdeDiffApprovalForEdit).
-    const ide = await tryIdeDiffApprovalForEdit(name, args, context, cwd, {
-      rule: `hook:${outcome.hook}`,
-      source: "PreToolUse hook",
-    });
-    if (ide?.outcome === "accepted") {
-      return { blocked: false, ideApplied: ide.result };
-    }
-    // Both rejected and changes-requested mean "not applied + feed the
-    // verdict's message back" — same control flow, different message body.
-    if (ide?.outcome === "rejected" || ide?.outcome === "changes-requested") {
-      return {
-        blocked: true,
-        reason: ide.result.error,
-        hook: outcome.hook,
-        ideResult: ide.result,
-      };
-    }
-    const ok = await requestInteractivePermission(name, args, context, cwd, {
-      tool: name,
-      args,
-      rule: `hook:${outcome.hook}`,
-      reason: outcome.reason || "a PreToolUse hook requests confirmation",
-    });
-    return ok
-      ? { blocked: false }
-      : {
-          blocked: true,
-          reason: outcome.reason || "PreToolUse hook ask denied",
-          hook: outcome.hook,
-        };
-  }
-  return { blocked: false };
-}
-
-/**
- * Run settings.json `PermissionRequest` hooks (Claude-Code parity). Fires at the
- * exact moment a tool call would prompt the user for approval — BEFORE the
- * prompt — so a policy hook can auto-approve (`allow`/`approve`), auto-reject
- * (`deny`/`block`), or defer (`ask` / no decision) to the normal prompt.
- * Returns `{ decision: "allow" | "deny" | null }`. No matching hook (or no
- * `settingsHooks`) → `{ decision: null }` and the caller prompts exactly as
- * before (default behaviour is byte-for-byte unchanged).
- * @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",
-    name,
-  );
-  if (!matched || matched.length === 0) return { decision: null };
-  const payload = withDeliveryId(
-    "PermissionRequest",
-    {
-      hook_event_name: "PermissionRequest",
-      tool_name: umbrellaFor(name),
-      raw_tool_name: name,
-      tool_input: args,
-      permission_reason: reason || null,
-      cwd,
-      session_id: context.sessionId || null,
-    },
-    {
-      sessionId: context.sessionId || null,
-      traceId: context.hookTraceId || null,
-      parentId: context.hookParentId || null,
-    },
-  );
-  const outcome = runCommandHooks(matched, payload, {
-    cwd,
-    event: "PermissionRequest",
-    mergeStrict: true,
-    failClosed: true,
-    broker,
-  });
-  // Precedence: deny > ask > allow > defer. The runner normalizes deny/block →
-  // "block" and short-circuits block/ask, but it COLLAPSES an "allow" into the
-  // aggregate "continue" (it only short-circuits block/ask) — so an explicit
-  // auto-approve must be recovered from the per-hook `results`. A deny or ask
-  // by any hook still wins over an allow (safety: never let an allow override a
-  // gate that another hook wanted to block or prompt for).
-  if (outcome.decision === "block") {
-    return { decision: "deny", reason: outcome.reason, hook: outcome.hook };
-  }
-  if (outcome.decision === "ask") {
-    return { decision: null }; // a hook asked → defer to the confirmer
-  }
-  const allowHook =
-    outcome.decision === "allow"
-      ? { command: outcome.hook }
-      : (outcome.results || []).find((r) => r && r.decision === "allow");
-  if (allowHook) {
-    return { decision: "allow", hook: allowHook.command || null };
-  }
-  return { decision: null }; // no actionable decision → defer to the confirmer
-}
-
 /**
  * Resolve an interactive permission gate. Gives `PermissionRequest` hooks first
  * say (auto-allow → true without prompting, auto-deny → false without
@@ -946,6 +788,12 @@ async function requestInteractivePermission(
       ? Boolean(await confirm(confirmArgs))
       : false;
   }
+  if (context.planReadOnlyFenceActive === true) {
+    const confirm = context.permissionConfirm || context.shellConfirm || null;
+    return typeof confirm === "function"
+      ? Boolean(await confirm(confirmArgs))
+      : false;
+  }
   const hooksV2 = await executeHooksV2Event(
     "PermissionRequest",
     {
@@ -954,14 +802,21 @@ async function requestInteractivePermission(
       turn_id: context.turnId || null,
       tool_use_id: context.toolCallId || null,
       tool_name: name,
+      raw_tool_name: name,
+      tool_input: args,
       input_keys:
         args && typeof args === "object" ? Object.keys(args).sort() : [],
       reason: confirmArgs?.reason || null,
       cwd,
-      trace_id: context.hookTraceId || null,
-      parent_id: context.hookParentId || null,
+      ...(context.hookTraceId ? { trace_id: context.hookTraceId } : {}),
+      ...(context.hookParentId ? { parent_id: context.hookParentId } : {}),
+    },
+    {
+      failClosed: true,
+      settingsHooks: context.settingsHooks,
+      matchTarget: name,
+      cwd,
     },
-    { failClosed: true },
   );
   if (hooksV2.decision === "allow") return true;
   if (hooksV2.blocked || hooksV2.decision === "block") {
@@ -975,25 +830,6 @@ async function requestInteractivePermission(
     });
     return false;
   }
-  const verdict = runSettingsPermissionRequestHooks(
-    name,
-    args,
-    context,
-    cwd,
-    confirmArgs?.reason,
-  );
-  if (verdict.decision === "allow") return true;
-  if (verdict.decision === "deny") {
-    emitHooksV2Event("PermissionDenied", {
-      schema_version: 1,
-      session_id: context.sessionId || null,
-      turn_id: context.turnId || null,
-      tool_use_id: context.toolCallId || null,
-      tool_name: name,
-      source: "settings-hook",
-    });
-    return false;
-  }
   const confirm = context.permissionConfirm || context.shellConfirm || null;
   const approved =
     typeof confirm === "function" ? await confirm(confirmArgs) : false;
@@ -2750,6 +2586,25 @@ export async function executeTool(name, args, context = {}) {
     typeof context.externalToolExecutors === "object"
       ? context.externalToolExecutors[name] || null
       : null;
+  // Bind MCP arguments to one strict immutable JSON snapshot before any
+  // asynchronous permission or Hook boundary. This prevents accessors,
+  // functions, or later caller mutation from changing the request that was
+  // approved, recorded in the ledger, and sent over the wire.
+  if (localToolExecutor?.kind === "mcp") {
+    try {
+      args = snapshotMcpJsonRpcInput(args || {});
+    } catch (error) {
+      return {
+        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 runtimeDescriptor =
     getRuntimeToolDescriptor(name) || localToolDescriptor;
   let admittedToolAdmissionDigest = null;
@@ -2852,6 +2707,8 @@ export async function executeTool(name, args, context = {}) {
         turn_id: context.turnId || null,
         tool_use_id: context.toolCallId || null,
         tool_name: name,
+        raw_tool_name: name,
+        tool_input: args,
         hook_event_name: event,
         hook_source: source,
         incident_code: incident.code,
@@ -3553,6 +3410,7 @@ export async function executeTool(name, args, context = {}) {
       "PreToolUse",
       {
         schema_version: 1,
+        event_id: `evt_${randomUUID().replaceAll("-", "").slice(0, 16)}`,
         session_id: context.sessionId || null,
         turn_id: context.turnId || null,
         tool_use_id: context.toolCallId || null,
@@ -3560,28 +3418,69 @@ export async function executeTool(name, args, context = {}) {
         input_keys:
           args && typeof args === "object" ? Object.keys(args).sort() : [],
         cwd,
-        trace_id: context.hookTraceId || null,
-        parent_id: context.hookParentId || null,
+        ...(context.hookTraceId ? { trace_id: context.hookTraceId } : {}),
+        ...(context.hookParentId ? { parent_id: context.hookParentId } : {}),
+      },
+      {
+        failClosed: true,
+        settingsHooks: context.settingsHooks,
+        hookDb,
+        matchTarget: name,
+        cwd,
       },
-      { failClosed: true },
     );
     if (hooksV2Pre.blocked || hooksV2Pre.decision === "block") {
+      const blockingHook = hooksV2Pre.results?.find(
+        (entry) => entry.decision === "block",
+      );
+      const blockingReason =
+        blockingHook?.result?.reason ||
+        hooksV2Pre.blockingResult?.reason ||
+        blockingHook?.error ||
+        null;
       return {
-        error: `[Hook v2] PreToolUse blocked "${name}".`,
-        policy: { decision: "block", via: "hooks-v2" },
+        error: `[Hook] PreToolUse blocked "${name}"${blockingReason ? `: ${blockingReason}` : ""}`,
+        policy: {
+          decision: "block",
+          via: "hook",
+          hook: blockingHook?.hookId || null,
+          code:
+            hooksV2Pre.errorCode ||
+            hooksV2Pre.auditError ||
+            hooksV2Pre.blockingResult?.code ||
+            null,
+        },
       };
     }
     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;
+      const askingHook = hooksV2Pre.results?.find(
+        (entry) => entry.decision === "ask",
+      );
+      const reason =
+        askingHook?.result?.reason ||
+        hooksV2Pre.blockingResult?.reason ||
+        "A PreToolUse Hook requests confirmation";
+      const ide = await tryIdeDiffApprovalForEdit(name, args, context, cwd, {
+        rule: `hook:${askingHook?.hookId || "canonical"}`,
+        source: "PreToolUse Hook",
+      });
+      if (ide?.outcome === "accepted") return ide.result;
+      if (ide?.outcome === "rejected" || ide?.outcome === "changes-requested") {
+        return ide.result;
+      }
+      const approved = await requestInteractivePermission(
+        name,
+        args,
+        context,
+        cwd,
+        {
+          tool: name,
+          args,
+          rule: `hook:${askingHook?.hookId || "canonical"}`,
+          reason,
+          source: "hooks-v2",
+        },
+      );
       if (!approved) {
         emitHooksV2Event("PermissionDenied", {
           schema_version: 1,
@@ -3592,35 +3491,8 @@ export async function executeTool(name, args, context = {}) {
           source: "hooks-v2",
         });
         return {
-          error: `[Hook v2] PreToolUse confirmation denied for "${name}".`,
-          policy: { decision: "deny", via: "hooks-v2" },
-        };
-      }
-    }
-    if (hookDb) {
-      try {
-        await executeHooks(hookDb, HookEvents.PreToolUse, {
-          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 },
+          error: `[Hook] PreToolUse blocked "${name}": confirmation denied`,
+          policy: { decision: "deny", via: "hook" },
         };
       }
     }
@@ -3741,19 +3613,26 @@ export async function executeTool(name, args, context = {}) {
         context.browserReplayAllowCredentials === true,
     });
   } catch (err) {
-    if (
-      hookDb &&
-      !planReadOnlyFenceActive &&
-      context.hermeticExecution !== true
-    ) {
+    if (!planReadOnlyFenceActive && context.hermeticExecution !== true) {
       try {
-        await executeHooks(hookDb, HookEvents.ToolError, {
-          tool: name,
-          args,
-          error: err.message,
-        });
+        await executeHooksV2Event(
+          "ToolError",
+          {
+            tool: name,
+            tool_name: name,
+            tool_input: args,
+            error: err.message,
+            cwd,
+          },
+          {
+            hookDb,
+            settingsHooks: context.settingsHooks,
+            matchTarget: name,
+            cwd,
+          },
+        );
       } catch (error) {
-        recordObserveHookIncident("ToolError", "database", error);
+        recordObserveHookIncident("ToolError", "canonical", error);
       }
     }
     throw err;
@@ -3777,96 +3656,76 @@ export async function executeTool(name, args, context = {}) {
     }
   }
 
-  // PostToolUse hook
-  if (
-    hookDb &&
-    !planReadOnlyFenceActive &&
-    context.hermeticExecution !== true
-  ) {
-    try {
-      await executeHooks(hookDb, HookEvents.PostToolUse, {
-        tool: name,
-        args,
-        result:
-          typeof toolResult === "object"
-            ? JSON.stringify(toolResult).substring(0, 500)
-            : String(toolResult).substring(0, 500),
-        descriptor: runtimeDescriptor,
-        context: toolContext,
-      });
-    } 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.
+  // Canonical PostToolUse dispatch. SQLite and settings definitions are input
+  // adapters; Hooks v2 is the only scheduler/decision/audit runtime.
   if (
     !planReadOnlyFenceActive &&
     context.hermeticExecution !== true &&
-    context.settingsHooks &&
     toolResult &&
     typeof toolResult === "object"
   ) {
     try {
-      const matched = collectHooks(context.settingsHooks, "PostToolUse", name);
-      if (matched && matched.length > 0) {
-        // `async:true` PostToolUse hooks must NOT block the tool loop — split
-        // them off the synchronous decision path. Without this an async hook
-        // ran synchronously here, defeating fire-and-forget (a background lint /
-        // test after each edit would stall the turn).
-        const { sync, async: asyncHooks } = partitionAsyncHooks(matched);
-        const payload = withDeliveryId(
-          "PostToolUse",
-          {
-            hook_event_name: "PostToolUse",
-            tool_name: umbrellaFor(name),
-            raw_tool_name: name,
-            tool_input: args,
-            tool_response:
-              typeof toolResult === "object"
-                ? JSON.stringify(toolResult).substring(0, 2000)
-                : String(toolResult).substring(0, 2000),
-            cwd,
-            session_id: context.sessionId || null,
-          },
-          {
-            sessionId: context.sessionId || null,
-            traceId: context.hookTraceId || null,
-            parentId: context.hookParentId || null,
-          },
-        );
-        if (sync.length > 0) {
-          const outcome = runCommandHooks(sync, payload, {
-            cwd,
-            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;
-          }
-        }
-        // Fire-and-forget the async hooks onto the REPL-owned supervisor when
-        // one is wired; results/rewakes drain into the next turn's context.
-        if (asyncHooks.length > 0 && context.hookSupervisor) {
-          context.hookSupervisor.dispatch(asyncHooks, payload, { cwd, broker });
+      const outcome = await executeHooksV2Event(
+        "PostToolUse",
+        {
+          schema_version: 1,
+          event_id: `evt_${randomUUID().replaceAll("-", "").slice(0, 16)}`,
+          hook_event_name: "PostToolUse",
+          tool_name: umbrellaFor(name),
+          raw_tool_name: name,
+          tool_input: args,
+          tool_response: JSON.stringify(toolResult).substring(0, 2000),
+          cwd,
+          session_id: context.sessionId || null,
+          ...(context.hookTraceId ? { trace_id: context.hookTraceId } : {}),
+          ...(context.hookParentId ? { parent_id: context.hookParentId } : {}),
+        },
+        {
+          settingsHooks: context.settingsHooks,
+          hookDb,
+          matchTarget: name,
+          cwd,
+          asyncDispatcher:
+            context.hookSupervisor &&
+            typeof context.hookSupervisor.dispatch === "function"
+              ? (hook, payload) =>
+                  context.hookSupervisor.dispatch(
+                    [hook.legacyHook || hook],
+                    payload,
+                    { cwd, broker },
+                  )
+              : null,
+        },
+      );
+      for (const hookResult of outcome.results || []) {
+        if (
+          hookResult?.status === "error" &&
+          String(hookResult.hookId || "").startsWith("settings:")
+        ) {
+          recordObserveHookIncident(
+            "PostToolUse",
+            "settings-command",
+            hookResult.error || "hook command failed",
+          );
         }
       }
+      const feedback = outcome.results?.find(
+        (entry) =>
+          entry.status === "success" &&
+          entry.result &&
+          ["block", "deny"].includes(
+            String(
+              entry.result.decision ||
+                entry.result.permissionDecision ||
+                entry.result.hookSpecificOutput?.permissionDecision ||
+                "",
+            ).toLowerCase(),
+          ),
+      );
+      const reason = feedback?.result?.reason;
+      if (reason) toolResult.hookFeedback = reason;
     } catch (error) {
-      recordObserveHookIncident("PostToolUse", "settings-command", error);
+      recordObserveHookIncident("PostToolUse", "canonical", error);
     }
   }
 
@@ -3885,7 +3744,7 @@ export async function executeTool(name, args, context = {}) {
     !(toolResult.background === true && toolResult.status === "running")
   ) {
     try {
-      const outcome = runObserveHooks(
+      const outcome = await runObserveHooks(
         context.settingsHooks,
         "SubagentStop",
         {
@@ -5813,7 +5672,7 @@ async function executeToolInner(
       // below so an allow rule can never re-enable a blocked unsafe command.
       const requestShellApproval = async (operationArgs) => {
         await shellDispatchPolicyAuthority?.revalidate?.();
-        if (approvalGate && !ruleAllowed) {
+        if (!ruleAllowed) {
           const approvalPolicyVersion = `${shellDispatchPolicyAuthority?.policyVersion || "cc-shell-policy-authority/v1:unobserved"}:shell:${shellPolicy.decision}:${shellPolicy.ruleId || "none"}`;
           const gated = await evaluateShellCommandWithApproval({
             command: args.command,
@@ -6209,6 +6068,43 @@ async function executeToolInner(
       );
       if (approvalDenial) return approvalDenial;
 
+      const createShellProcessAuditContext = () => {
+        const authorization = approvalOutcome || {
+          decision: "allow",
+          via: ruleAllowed ? "settings-rule" : "shell-policy",
+          riskLevel: null,
+          policy: null,
+        };
+        const policyDigest = createHash("sha256")
+          .update(
+            JSON.stringify({
+              authorityVersion:
+                shellDispatchPolicyAuthority?.policyVersion || null,
+              shellDecision: shellPolicy.decision || null,
+              shellRuleId: shellPolicy.ruleId || null,
+              authorization,
+            }),
+            "utf8",
+          )
+          .digest("hex");
+        return Object.freeze({
+          actor: "agent",
+          sessionId: sessionId ? String(sessionId) : null,
+          authorization: Object.freeze({ ...authorization }),
+          policyDigest,
+        });
+      };
+      const shellProcessAuditRedactArgIndexes = () => {
+        const auditArgs = pluginBinInvocation
+          ? executionPlugin?.argv
+          : shellInv.useDefaultShell
+            ? []
+            : shellInv.argv;
+        return Array.isArray(auditArgs)
+          ? auditArgs.map((_, index) => index)
+          : [];
+      };
+
       let shellDispatchAdmitted = false;
       const admitShellDispatch = async () => {
         if (shellDispatchAdmitted) {
@@ -6337,6 +6233,10 @@ async function executeToolInner(
             policy: "allow",
             scope: "agent",
             sandboxPolicy: pluginBinSandboxPolicy,
+            requirePersistentAudit: true,
+            auditRedactCommand: true,
+            auditRedactArgIndexes: [launchArgs.length - 1],
+            auditContext: createShellProcessAuditContext(),
           };
           const issuer =
             _backgroundProcessDeps.issueLinuxWorkspaceSandboxExecutionContract;
@@ -6447,6 +6347,10 @@ async function executeToolInner(
                 origin: processOrigin,
                 policy: "allow",
                 scope: "agent",
+                requirePersistentAudit: true,
+                auditRedactCommand: true,
+                auditRedactArgIndexes: shellProcessAuditRedactArgIndexes(),
+                auditContext: createShellProcessAuditContext(),
                 ...processProvenance,
               }
             : null;
@@ -6638,6 +6542,7 @@ async function executeToolInner(
             maxBuffer: 1024 * 1024,
             egressProxy,
             env: sandboxChildEnvironment,
+            auditContext: createShellProcessAuditContext(),
           });
         } finally {
           if (proxyHandle) {
@@ -6697,6 +6602,10 @@ async function executeToolInner(
           origin: processOrigin,
           policy: "allow",
           scope: "agent",
+          requirePersistentAudit: true,
+          auditRedactCommand: true,
+          auditRedactArgIndexes: shellProcessAuditRedactArgIndexes(),
+          auditContext: createShellProcessAuditContext(),
           ...processProvenance,
         };
         if (pluginBinInvocation) {
@@ -8358,20 +8267,9 @@ 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"),
-            },
-          });
-        }
+        // executeTool admitted this immutable snapshot before permission and
+        // Hook processing; reuse the exact object for ledger and transport.
+        const mcpWireInput = args;
 
         if (
           mcpDispatchAdmission !== null &&
@@ -9885,7 +9783,7 @@ async function _executeSpawnSubAgent(args, ctx) {
   // returns). Best-effort — a hook error never blocks the spawn.
   if (ctx.settingsHooks) {
     try {
-      const startOutcome = runObserveHooks(
+      const startOutcome = await runObserveHooks(
         ctx.settingsHooks,
         "SubagentStart",
         {
@@ -10650,14 +10548,40 @@ export async function chatWithTools(rawMessages, options) {
     options.providerRequestId,
   );
 
-  const tools = getEffectiveToolDefinitions(options);
+  let tools = getEffectiveToolDefinitions(options);
+  if (Array.isArray(options.contextMemorySelectedToolNames)) {
+    const selected = new Set(options.contextMemorySelectedToolNames);
+    tools = tools.filter((tool) => selected.has(tool?.function?.name));
+  }
 
-  const lastUserMsg = [...rawMessages].reverse().find((m) => m.role === "user");
-  const messages = ce
-    ? ce.buildOptimizedMessages(rawMessages, {
-        userQuery: lastUserMsg?.content,
-      })
-    : rawMessages;
+  let providerMessages = rawMessages;
+  let canonicalPlan = null;
+  if (
+    options.contextMemoryPreplanned !== true &&
+    options.contextMemorySkipPlanning !== true
+  ) {
+    const { prepareCanonicalProviderContext } =
+      await import("../lib/context-memory-kernel/provider-context.js");
+    const prepared = await prepareCanonicalProviderContext(rawMessages, {
+      ...options,
+      contextMemoryToolDefinitions: tools,
+    });
+    providerMessages = prepared.messages;
+    canonicalPlan = prepared.plan;
+    if (canonicalPlan) {
+      const selected = new Set(prepared.selectedToolNames);
+      tools = tools.filter((tool) => selected.has(tool?.function?.name));
+    }
+  }
+  const lastUserMsg = [...providerMessages]
+    .reverse()
+    .find((m) => m.role === "user");
+  const messages =
+    ce && !canonicalPlan
+      ? ce.buildOptimizedMessages(providerMessages, {
+          userQuery: lastUserMsg?.content,
+        })
+      : providerMessages;
 
   throwIfAborted(signal);
 
@@ -12775,9 +12699,19 @@ async function _getAutoCompactor(options) {
     return _instrumentAutoCompactorUsage(options._autoCompactor, options);
   }
   let compressor = null;
+  let canonicalRequired = false;
   try {
     const { feature } = await import("../lib/feature-flags.js");
-    if (feature("PROMPT_COMPRESSOR")) {
+    const { resolveCliContextMemoryCutover } =
+      await import("../lib/context-memory-kernel/authority.js");
+    const cutover = resolveCliContextMemoryCutover({
+      env: options.contextMemoryEnv || process.env,
+      scopeKey: options.sessionId
+        ? `cli:session:${options.sessionId}`
+        : "cli:live-session",
+    });
+    canonicalRequired = cutover.canonical;
+    if (feature("PROMPT_COMPRESSOR") || cutover.canonical) {
       const { PromptCompressor } =
         await import("../harness/prompt-compressor.js");
       const llmQuery =
@@ -12798,6 +12732,7 @@ async function _getAutoCompactor(options) {
                   {
                     ...options,
                     contextEngine: null,
+                    contextMemorySkipPlanning: true,
                     enabledToolNames: [],
                     extraToolDefinitions: [],
                     hostManagedToolPolicy: null,
@@ -12824,8 +12759,35 @@ async function _getAutoCompactor(options) {
         summaryInputMaxChars: options.compactionInputMaxChars,
       });
       compressor = _instrumentAutoCompactorUsage(compressor, options);
+      if (cutover.canonical) {
+        const compatibilitySummarizer = compressor;
+        const { compactLiveMessagesCanonical } =
+          await import("../lib/context-memory-kernel/live-compaction.js");
+        compressor = {
+          canonicalKernel: true,
+          shouldAutoCompact: (messages) =>
+            compatibilitySummarizer.shouldAutoCompact(messages),
+          compress: async (messages, compressOptions = {}) => {
+            return compactLiveMessagesCanonical(messages, {
+              compressor: compatibilitySummarizer,
+              compressOptions,
+              sessionId: options.sessionId,
+              operationId: `auto-${randomUUID()}`,
+              provider: options.provider,
+              model: options.model,
+              env: options.contextMemoryEnv || process.env,
+              persist: options.persistCompaction !== false,
+              trigger: "auto",
+              ...(typeof options.onCompaction === "function"
+                ? { commit: options.onCompaction }
+                : {}),
+            });
+          },
+        };
+      }
     }
-  } catch {
+  } catch (error) {
+    if (canonicalRequired) throw error;
     compressor = null;
   }
   try {
@@ -12906,7 +12868,9 @@ async function _settleAutomaticCompaction({
   }
 
   let settlement = null;
-  if (typeof options.onCompaction === "function") {
+  if (stats?.canonicalAlreadySettled === true) {
+    settlement = stats.canonicalReceipt || null;
+  } else if (typeof options.onCompaction === "function") {
     if (options.onCompaction.constructor?.name === "AsyncFunction") {
       throw _compactionSettlementError(
         "CC_COMPACTION_SETTLEMENT_ASYNC",
@@ -13597,7 +13561,10 @@ export async function* agentLoop(messages, options) {
           // the full compaction below is skipped this round — so heavy-tool
           // conversations rarely hit a full summarize. Opt out:
           // autoMicroCompact: false.
-          if (options.autoMicroCompact !== false) {
+          if (
+            options.autoMicroCompact !== false &&
+            compactor.canonicalKernel !== true
+          ) {
             try {
               const { microCompact } = await import("../lib/micro-compact.js");
               const mc = microCompact(messages);
@@ -13623,7 +13590,7 @@ export async function* agentLoop(messages, options) {
           let preCompactReason = null;
           if (!hermeticExecution && needFull && options.settingsHooks) {
             try {
-              const pc = runObserveHooks(
+              const pc = await runObserveHooks(
                 options.settingsHooks,
                 "PreCompact",
                 {
@@ -13670,6 +13637,31 @@ export async function* agentLoop(messages, options) {
                 preserveToolPairs: true,
                 ...pinOpts,
               });
+          if (
+            stats?.canonicalReceipt &&
+            !["committed", "degraded"].includes(stats.canonicalReceipt.status)
+          ) {
+            automaticCompactionSettlementBlocked = true;
+            yield {
+              type: "compaction-degraded",
+              runId,
+              reason:
+                stats.canonicalReceipt.status === "stale"
+                  ? "session_messages_changed_during_compaction"
+                  : "canonical_compaction_reconciliation_required",
+              summaryMode: "none",
+              code:
+                stats.canonicalReceipt.status === "stale"
+                  ? "SESSION_REVISION_STALE"
+                  : "CC_COMPACTION_RECONCILIATION_REQUIRED",
+              receipt: stats.canonicalReceipt,
+            };
+            await _awaitBackgroundUsageSettlement(
+              backgroundSubAgents,
+              backgroundUsageFailureState,
+            );
+            return;
+          }
           const observerFailure = compactionUsageState.calls.find(
             (call) => call.observerFailed,
           );
@@ -13937,7 +13929,7 @@ export async function* agentLoop(messages, options) {
         // spawn-time handle skips it); a block reason rides along as feedback.
         if (!hermeticExecution && options.settingsHooks) {
           try {
-            const outcome = runObserveHooks(
+            const outcome = await runObserveHooks(
               options.settingsHooks,
               "SubagentStop",
               {
@@ -13982,6 +13974,7 @@ export async function* agentLoop(messages, options) {
     // prepareCall runs fresh each iteration and returns an ephemeral
     // system-message supplement that is NOT persisted to messages history.
     let callMessages = messages;
+    const contextMemoryTrustedSystemIndexes = [];
     if (!hermeticExecution && typeof options.prepareCall === "function") {
       try {
         const hook = await options.prepareCall({
@@ -13998,6 +13991,7 @@ export async function* agentLoop(messages, options) {
             ...messages,
             { role: "system", content: hook.systemSuffix },
           ];
+          contextMemoryTrustedSystemIndexes.push(callMessages.length - 1);
         }
       } catch (_e) {
         // prepareCall failures are non-critical — proceed with original messages
@@ -14010,6 +14004,29 @@ export async function* agentLoop(messages, options) {
     // model request within that turn. Normalized through buildTelemetryAttributes
     // so they get the same charset-sanitized + cardinality-bounded treatment as
     // the run-level ids (turn.id correlates with the agent.iteration counter).
+    let canonicalProviderContext = null;
+    if (options.contextMemorySkipPlanning !== true) {
+      const { prepareCanonicalProviderContext } =
+        await import("../lib/context-memory-kernel/provider-context.js");
+      canonicalProviderContext = await prepareCanonicalProviderContext(
+        callMessages,
+        {
+          ...options,
+          contextMemoryToolDefinitions:
+            getEffectiveToolDefinitions(effectiveToolOptions),
+          contextMemoryTrustedSystemIndexes,
+        },
+      );
+      if (canonicalProviderContext.plan) {
+        callMessages = canonicalProviderContext.messages;
+        yield {
+          type: "context.plan.created",
+          plan: canonicalProviderContext.plan,
+          recallDigest: canonicalProviderContext.recall?.digest || null,
+        };
+      }
+    }
+
     const modelIdAttrs = recorder
       ? buildTelemetryAttributes({
           turnId: `${runId}:t${budget.consumed}`,
@@ -14024,9 +14041,18 @@ export async function* agentLoop(messages, options) {
       "model",
       budget.consumed,
     );
-    const providerCallOptions = providerRequestId
-      ? { ...effectiveToolOptions, providerRequestId }
+    const plannedProviderOptions = canonicalProviderContext?.plan
+      ? {
+          ...effectiveToolOptions,
+          contextEngine: null,
+          contextMemoryPreplanned: true,
+          contextMemorySelectedToolNames:
+            canonicalProviderContext.selectedToolNames,
+        }
       : effectiveToolOptions;
+    const providerCallOptions = providerRequestId
+      ? { ...plannedProviderOptions, providerRequestId }
+      : plannedProviderOptions;
     const modelUsageCall = {
       type: "model-usage-started",
       callId: _newModelUsageCallId("model"),
@@ -14275,7 +14301,7 @@ export async function* agentLoop(messages, options) {
       if (!hermeticExecution && options.settingsHooks) {
         let stopOutcome = null;
         try {
-          stopOutcome = runObserveHooks(
+          stopOutcome = await runObserveHooks(
             options.settingsHooks,
             "Stop",
             {