chainlesschain 0.162.166 → 0.162.168

package/src/runtime/agent-core.js

@@ -28,6 +28,11 @@ import { mergeProviderOptions } from "../lib/provider-options.js";
 import { applyCredentialProxy } from "../lib/credential-proxy.js";
 import { describeBackgroundCommand } from "../lib/terminal-context.js";
 import { buildTelemetryAttributes } from "../lib/telemetry-ids.js";
+import {
+  workspaceRootsFor,
+  pickRootForFile,
+  mergeWorkspaceSymbolResults,
+} from "../lib/lsp/workspace-roots.js";
 import { getPlanModeManager } from "../lib/plan-mode.js";
 import { CLISkillLoader } from "../lib/skill-loader.js";
 import { executeHooks, HookEvents } from "../lib/hook-manager.js";
@@ -91,9 +96,14 @@ const { isDangerousGitCommand, isReadOnlyGitCommand, normalizeGitCommand } =
 const { evaluateShellCommandPolicy } = sharedShellPolicy;
 const { evaluatePermissionRules } = sharedPermissionRules;
 const { collectHooks, umbrellaFor } = sharedSettingsHooks;
-const { runHooks: runCommandHooks } = sharedHookRunner;
-const { runObserveHooks, aggregateContext, partitionAsyncHooks } =
-  sharedHookEvents;
+const { runHooks: runCommandHooks, runHooksParallel: runCommandHooksParallel } =
+  sharedHookRunner;
+const {
+  runObserveHooks,
+  aggregateContext,
+  partitionAsyncHooks,
+  withDeliveryId,
+} = sharedHookEvents;
 
 // ─── Background shell tasks ────────────────────────────────────────────────
 //
@@ -409,6 +419,19 @@ 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`
@@ -419,18 +442,36 @@ function _resolveShellTimeout(raw) {
 async function runSettingsPreToolUseHooks(name, args, context, cwd) {
   const matched = collectHooks(context.settingsHooks, "PreToolUse", name);
   if (!matched || matched.length === 0) return { blocked: false };
-  const payload = {
-    hook_event_name: "PreToolUse",
-    tool_name: umbrellaFor(name),
-    raw_tool_name: name,
-    tool_input: args,
-    cwd,
-    session_id: context.sessionId || null,
-  };
-  const outcome = runCommandHooks(matched, payload, {
-    cwd,
-    event: "PreToolUse",
-  });
+  // 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,
+    },
+  );
+  // 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",
+      })
+    : runCommandHooks(matched, payload, { cwd, event: "PreToolUse" });
   if (outcome.decision === "block") {
     return { blocked: true, reason: outcome.reason, hook: outcome.hook };
   }
@@ -490,18 +531,27 @@ function runSettingsPermissionRequestHooks(name, args, context, cwd, reason) {
     name,
   );
   if (!matched || matched.length === 0) return { decision: null };
-  const payload = {
-    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,
-  };
+  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: _hookStrictMergeEnabled(),
   });
   // Precedence: deny > ask > allow > defer. The runner normalizes deny/block →
   // "block" and short-circuits block/ask, but it COLLAPSES an "allow" into the
@@ -726,6 +776,7 @@ Key behaviors:
 - When asked about files or code, use read_file and search_files to find information
 - Before renaming or changing a symbol, use code_intelligence (action: references/definition) to find every real usage instead of guessing with text search. It degrades to "unavailable" when no language server is installed — fall back to search_files then.
 - After an edit, if the tool result includes a "newDiagnostics" array, you just introduced (or exposed) those errors/warnings — read them and fix before moving on. You can also run code_intelligence (action: diagnostics) on any file to check it on demand.
+- If a tool result includes a "subtreeInstructions" array, you just entered a subdirectory that carries its own cc.md/CLAUDE.md/AGENTS.md — treat that content as authoritative project rules for work in that subtree (it is injected once, the first time you touch the subtree).
 - You have multi-layer skills (built-in, marketplace, global, project-level) — use list_skills to discover them and run_skill to execute them
 - Always explain what you're doing and show results
 - Be concise but thorough
@@ -1642,18 +1693,26 @@ export async function executeTool(name, args, context = {}) {
         // 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 = {
-          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,
-        };
+        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,
@@ -1700,7 +1759,11 @@ export async function executeTool(name, args, context = {}) {
               ? JSON.stringify(toolResult).substring(0, 2000)
               : String(toolResult).substring(0, 2000),
         },
-        { cwd },
+        {
+          cwd,
+          traceId: context.hookTraceId || null,
+          parentId: context.hookParentId || null,
+        },
       );
       if (outcome.decision === "block" && outcome.reason) {
         toolResult.hookFeedback = toolResult.hookFeedback
@@ -2056,6 +2119,21 @@ const _codeIntelPool = new Map(); // root -> { ci, idleTimer }
 const CODE_INTEL_IDLE_MS = 60_000;
 let _codeIntelExitHooked = false;
 
+// Restart backoff between language-server re-spawns (P2 LSP): DEFAULT ON at a
+// 1s base (1s→2s→4s→8s cap, see lsp-manager) so a server that crashes on
+// startup can't burst `maxRestarts` spawns back-to-back before quarantine.
+// `CC_LSP_RESTART_BACKOFF_MS` overrides the base; 0 restores the legacy
+// immediate-respawn behavior.
+const DEFAULT_LSP_RESTART_BACKOFF_MS = 1000;
+function _lspRestartBackoffBaseMs() {
+  const raw = process.env.CC_LSP_RESTART_BACKOFF_MS;
+  if (raw !== undefined && raw !== "") {
+    const n = Number(raw);
+    if (Number.isFinite(n)) return Math.max(0, n);
+  }
+  return DEFAULT_LSP_RESTART_BACKOFF_MS;
+}
+
 export async function _getSharedCodeIntel(cwd) {
   const root = path.resolve(cwd || process.cwd());
   let entry = _codeIntelPool.get(root);
@@ -2075,7 +2153,11 @@ export async function _getSharedCodeIntel(cwd) {
     entry = _codeIntelPool.get(root);
     if (!entry) {
       entry = {
-        ci: new CodeIntelligence({ projectRoot: root, coldStart: true }),
+        ci: new CodeIntelligence({
+          projectRoot: root,
+          coldStart: true,
+          lspOptions: { restartBackoffBaseMs: _lspRestartBackoffBaseMs() },
+        }),
         idleTimer: null,
       };
       _codeIntelPool.set(root, entry);
@@ -2152,7 +2234,17 @@ async function _postEditDiagnostics(filePath, cwd) {
       const diags = (res.diagnostics || []).filter(
         (d) => d.severity === "error" || d.severity === "warning",
       );
-      return diags.length ? diags.slice(0, 20) : null;
+      if (!diags.length) return null;
+      // Bound by a TOKEN budget, severity-prioritized (errors survive over
+      // warnings), replacing the arbitrary unsorted count-cap of 20. Guarantees
+      // the model sees the most severe diagnostics first and can't be flooded by
+      // a pathological diagnostics dump. Budget is overridable via
+      // CC_EDIT_DIAGNOSTICS_TOKENS (default 2000).
+      const { capDiagnostics } =
+        await import("../lib/lsp/diagnostics-scheduler.js");
+      const budget = Number(process.env.CC_EDIT_DIAGNOSTICS_TOKENS) || 2000;
+      const { kept } = capDiagnostics(diags, { maxTokens: budget });
+      return kept.length ? kept : null;
     } catch {
       return null;
     }
@@ -2176,6 +2268,96 @@ async function _withPostEditDiagnostics(result, filePath, cwd) {
   return newDiagnostics ? { ...result, newDiagnostics } : result;
 }
 
+// ─── Lazy subtree instruction injection (large-monorepo lever) ─────────────
+//
+// cc.md / CLAUDE.md / AGENTS.md that sit BELOW the startup cwd are intentionally
+// 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
+// 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
+
+async function _getSubtreeLoader(cwd) {
+  const root = path.resolve(cwd || process.cwd());
+  let loader = _subtreeLoaderPool.get(root);
+  if (!loader) {
+    const { SubtreeInstructionLoader } =
+      await import("../lib/project-instructions.js");
+    let instructionExcludes;
+    try {
+      const { readStringArraySetting } =
+        await import("../lib/settings-loader.cjs");
+      instructionExcludes = readStringArraySetting("instructionExcludes", {
+        cwd: root,
+      });
+    } catch {
+      instructionExcludes = undefined; // fail-open — honor no excludes
+    }
+    loader = new SubtreeInstructionLoader({
+      repoRoot: root,
+      baseDir: root,
+      instructionExcludes,
+    });
+    _subtreeLoaderPool.set(root, loader);
+  }
+  return loader;
+}
+
+/** Test/shutdown hook: forget every remembered subtree-injection set. */
+export function _resetSubtreeInstructionLoaders() {
+  _subtreeLoaderPool.clear();
+}
+
+/**
+ * Freshly-discovered subtree instruction files for a path a tool just touched,
+ * 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) {
+  if (process.env.CC_SUBTREE_INSTRUCTIONS === "0") return null;
+  try {
+    const loader = await _getSubtreeLoader(cwd);
+    const fresh = loader.onAccess(accessedPath);
+    if (!fresh || !fresh.length) return null;
+    const { DEFAULT_MAX_FILE_BYTES } =
+      await import("../lib/project-instructions.js");
+    const out = [];
+    for (const f of fresh) {
+      try {
+        const buf = fs.readFileSync(f.path);
+        const truncated = buf.length > DEFAULT_MAX_FILE_BYTES;
+        const content = (
+          truncated ? buf.slice(0, DEFAULT_MAX_FILE_BYTES) : buf
+        ).toString("utf-8");
+        out.push({
+          path: f.path,
+          scope: f.scope || "project",
+          content,
+          ...(truncated ? { truncated: true } : {}),
+        });
+      } catch {
+        // discovered file vanished before we could read it — skip it
+      }
+    }
+    return out.length ? out : null;
+  } catch {
+    return null; // fail-open: never break a tool because injection errored
+  }
+}
+
+/**
+ * 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) {
+  if (result && result.error) return result;
+  const subtreeInstructions = await _subtreeInstructionsFor(accessedPath, cwd);
+  return subtreeInstructions ? { ...result, subtreeInstructions } : result;
+}
+
 /**
  * Drop skills whose `paths:` frontmatter scopes them to a different subtree than
  * the agent's cwd (large-monorepo lazy skill surface). A skill with no `paths`
@@ -2230,6 +2412,9 @@ async function executeToolInner(
     signal = null,
     backgroundSubAgents = null,
     subAgentUsageSink = null,
+    // Hook-envelope tracing: this run's trace id, threaded into child loops
+    // (spawn_sub_agent / isolated run_skill) as their parent_id.
+    hookTraceId = null,
   },
 ) {
   const localToolDescriptor =
@@ -2338,18 +2523,30 @@ async function executeToolInner(
       }
 
       if (rendered.length > 50000) {
-        return attachDescriptor({
-          content: rendered.substring(0, 50000) + "\n...(truncated)",
-          size: rendered.length,
-          hashed: args.hashed === true,
-          ...(range ? { range } : {}),
-        });
+        return attachDescriptor(
+          await _withSubtreeInstructions(
+            {
+              content: rendered.substring(0, 50000) + "\n...(truncated)",
+              size: rendered.length,
+              hashed: args.hashed === true,
+              ...(range ? { range } : {}),
+            },
+            filePath,
+            cwd,
+          ),
+        );
       }
-      return attachDescriptor({
-        content: rendered,
-        hashed: args.hashed === true,
-        ...(range ? { range } : {}),
-      });
+      return attachDescriptor(
+        await _withSubtreeInstructions(
+          {
+            content: rendered,
+            hashed: args.hashed === true,
+            ...(range ? { range } : {}),
+          },
+          filePath,
+          cwd,
+        ),
+      );
     }
 
     case "write_file": {
@@ -2368,8 +2565,12 @@ async function executeToolInner(
       if (wrote.error) return attachDescriptor({ error: wrote.error });
       _recordFileObservation(filePath);
       return attachDescriptor(
-        await _withPostEditDiagnostics(
-          { success: true, path: filePath, size: wrote.size },
+        await _withSubtreeInstructions(
+          await _withPostEditDiagnostics(
+            { success: true, path: filePath, size: wrote.size },
+            filePath,
+            cwd,
+          ),
           filePath,
           cwd,
         ),
@@ -2457,13 +2658,17 @@ async function executeToolInner(
       if (wrote.error) return attachDescriptor({ error: wrote.error });
       _recordFileObservation(filePath);
       return attachDescriptor(
-        await _withPostEditDiagnostics(
-          {
-            success: true,
-            path: filePath,
-            size: wrote.size,
-            replaced: replaceAll ? count : 1,
-          },
+        await _withSubtreeInstructions(
+          await _withPostEditDiagnostics(
+            {
+              success: true,
+              path: filePath,
+              size: wrote.size,
+              replaced: replaceAll ? count : 1,
+            },
+            filePath,
+            cwd,
+          ),
           filePath,
           cwd,
         ),
@@ -2515,14 +2720,18 @@ async function executeToolInner(
       if (wrote.error) return attachDescriptor({ error: wrote.error });
       _recordFileObservation(filePath);
       return attachDescriptor(
-        await _withPostEditDiagnostics(
-          {
-            success: true,
-            path: filePath,
-            size: wrote.size,
-            lineNumber: result.lineNumber,
-            previousContent: result.previousContent,
-          },
+        await _withSubtreeInstructions(
+          await _withPostEditDiagnostics(
+            {
+              success: true,
+              path: filePath,
+              size: wrote.size,
+              lineNumber: result.lineNumber,
+              previousContent: result.previousContent,
+            },
+            filePath,
+            cwd,
+          ),
           filePath,
           cwd,
         ),
@@ -3104,6 +3313,8 @@ async function executeToolInner(
           subAgentBudget,
           subAgentContract,
           settingsHooks,
+          // 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,
@@ -3675,8 +3886,15 @@ async function executeToolInner(
           error: `code_intelligence action "rename_preview" requires "new_name".`,
         });
       }
-      const ci = await _getSharedCodeIntel(cwd);
+      // Multi-root workspace (P2 LSP): key the shared server pool on the root
+      // that actually CONTAINS the file — a file inside an `--add-dir` root
+      // gets that project's language server, not the cwd's. Single-root
+      // sessions resolve to cwd exactly as before (byte-identical).
       const file = args.file ? path.resolve(cwd, args.file) : null;
+      const wsRoots = workspaceRootsFor(cwd, additionalDirectories);
+      const ci = await _getSharedCodeIntel(
+        file ? pickRootForFile(file, wsRoots) : cwd,
+      );
       let res;
       try {
         switch (action) {
@@ -3692,9 +3910,29 @@ async function executeToolInner(
           case "document_symbols":
             res = await ci.documentSymbols(file);
             break;
-          case "workspace_symbols":
-            res = await ci.workspaceSymbols(String(args.query));
+          case "workspace_symbols": {
+            // Fan out across EVERY workspace root and merge — symbols from an
+            // --add-dir project are stamped with their `root` so same-named
+            // symbols stay unambiguous. One root → the exact legacy call.
+            if (wsRoots.length > 1) {
+              const perRoot = [];
+              for (const r of wsRoots) {
+                try {
+                  const rci = await _getSharedCodeIntel(r);
+                  perRoot.push(await rci.workspaceSymbols(String(args.query)));
+                } catch (err) {
+                  perRoot.push({
+                    available: false,
+                    reason: err?.message || "workspace_symbols failed",
+                  });
+                }
+              }
+              res = mergeWorkspaceSymbolResults(perRoot, wsRoots);
+            } else {
+              res = await ci.workspaceSymbols(String(args.query));
+            }
             break;
+          }
           case "diagnostics":
             res = await ci.diagnostics(file);
             break;
@@ -3743,12 +3981,18 @@ async function executeToolInner(
         });
       }
       const entries = fs.readdirSync(dirPath, { withFileTypes: true });
-      return attachDescriptor({
-        entries: entries.map((e) => ({
-          name: e.name,
-          type: e.isDirectory() ? "dir" : "file",
-        })),
-      });
+      return attachDescriptor(
+        await _withSubtreeInstructions(
+          {
+            entries: entries.map((e) => ({
+              name: e.name,
+              type: e.isDirectory() ? "dir" : "file",
+            })),
+          },
+          dirPath,
+          cwd,
+        ),
+      );
     }
 
     case "run_skill": {
@@ -3788,6 +4032,7 @@ async function executeToolInner(
           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"],
+          hookParentTraceId: hookTraceId || null,
           cwd,
           onUsage: skillUsageSink
             ? (u) => {
@@ -4251,6 +4496,32 @@ async function _executeRunCode(args, cwd) {
             };
           }
 
+          // Unified install-command audit (P0 sandbox slice): the same opt-in
+          // trail (CC_INSTALL_AUDIT / settings installPolicy) that records
+          // run_shell installs also records run_code auto-installs — one audit
+          // file covers every "fetch and run third-party code" entry point.
+          // Best-effort; default (policy off) writes nothing.
+          let auditUnifiedInstall = () => {};
+          try {
+            const icp = await import("../lib/install-command-policy.js");
+            const unified = icp.resolveInstallPolicy({});
+            if (unified.audit) {
+              const installCommand = `${interpreter} -m pip install ${packageName}`;
+              const cls = icp.classifyInstallCommand(installCommand);
+              auditUnifiedInstall = (outcome, detail) =>
+                icp.recordInstallCommandAudit({
+                  source: "run_code_auto_install",
+                  command: installCommand,
+                  outcome,
+                  ...(detail ? { detail } : {}),
+                  installs: cls.installs,
+                  global: icp.hasGlobalInstall(cls),
+                });
+            }
+          } catch {
+            /* unified audit must never affect the install itself */
+          }
+
           // Attempt pip install
           try {
             execSync(`${interpreter} -m pip install ${packageName}`, {
@@ -4265,6 +4536,7 @@ async function _executeRunCode(args, cwd) {
               cwd,
               outcome: "installed",
             });
+            auditUnifiedInstall("installed");
 
             // Retry execution
             const retryStart = Date.now();
@@ -4292,6 +4564,10 @@ async function _executeRunCode(args, cwd) {
               outcome: "failed",
               detail: (pipErr.stderr || pipErr.message || "").substring(0, 200),
             });
+            auditUnifiedInstall(
+              "failed",
+              (pipErr.stderr || pipErr.message || "").substring(0, 200),
+            );
             return {
               error: (stderr || message).substring(0, 5000),
               stderr: stderr.substring(0, 5000),
@@ -4556,6 +4832,8 @@ async function _executeSpawnSubAgent(args, ctx) {
   let mdProfile = null;
   let mdModel = null;
   let mdContract = null; // agent-file's normalized subagent contract (definition)
+  let mdSparsePaths = null; // agent-file worktree sparse-checkout paths
+  let mdSymlinkDirectories = null; // agent-file worktree dep-dir symlinks
   if (args.agent) {
     try {
       const { getAgent } = await import("../lib/agents.js");
@@ -4574,6 +4852,10 @@ async function _executeSpawnSubAgent(args, ctx) {
       if (!subIsolation && md.isolation === "worktree") {
         subIsolation = "worktree";
       }
+      if (md.sparsePaths != null) mdSparsePaths = md.sparsePaths;
+      if (md.symlinkDirectories != null) {
+        mdSymlinkDirectories = md.symlinkDirectories;
+      }
       if (md.model) mdModel = md.model;
       if (md.contract) mdContract = md.contract;
       if (md.systemPrompt) {
@@ -4894,10 +5176,37 @@ async function _executeSpawnSubAgent(args, ctx) {
       }
     : null;
 
+  // Worktree sparse-checkout + dependency symlink (large-monorepo lever): when
+  // the child runs in an isolated worktree, only materialize the packages it
+  // needs (sparsePaths) and reuse approved dep dirs (e.g. node_modules) from the
+  // main checkout (symlinkDirectories). Mirrors the team-worktree passthrough;
+  // spawn args win over the agent-file's values. Resolved ONLY when isolation is
+  // on → absent for a non-worktree spawn = byte-identical (full checkout).
+  let subWorktreeOptions = null;
+  if (subIsolation === "worktree") {
+    try {
+      const { normalizeSparsePaths } =
+        await import("../lib/worktree-sparse.js");
+      const sparse = normalizeSparsePaths(
+        args.sparsePaths ?? mdSparsePaths ?? null,
+      );
+      const symlink = args.symlinkDirectories ?? mdSymlinkDirectories ?? null;
+      const wtOpts = {};
+      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
+    }
+  }
+
   const subCtx = SubAgentContext.create({
     role,
     task,
     parentId: parentSessionId,
+    // Hook-envelope tracing: the child loop stamps its own runId as trace_id
+    // and THIS run's id as parent_id on every settings-hook payload it fires.
+    hookParentTraceId: ctx.hookTraceId || null,
     inheritedContext: resolvedContext,
     allowedTools: allowedTools || null,
     cwd: ctx.cwd,
@@ -4912,6 +5221,9 @@ async function _executeSpawnSubAgent(args, ctx) {
     // worktree isolation. undefined keeps the profile/flag defaults intact.
     ...(subMaxTurns ? { maxIterations: subMaxTurns } : {}),
     ...(subIsolation === "worktree" ? { useWorktree: true } : {}),
+    // Worktree sparse-checkout / dep-symlink options (large-monorepo); only
+    // present for a worktree spawn that requested them (else full checkout).
+    ...(subWorktreeOptions ? { worktreeOptions: subWorktreeOptions } : {}),
     // Resolved contract (gap 2026-07-12): cap the child's token budget and hand
     // it its EFFECTIVE contract so its OWN spawns inherit this ceiling.
     ...(effectiveContract?.budget?.tokens
@@ -4993,7 +5305,15 @@ async function _executeSpawnSubAgent(args, ctx) {
   // refuses to finish while any background sub-agent is still running). Only
   // available when the calling loop provided the per-run map — a bare
   // executeTool() without it falls through to the blocking path.
-  if (args.background === true && ctx.backgroundSubAgents instanceof Map) {
+  //
+  // `background` is driven by the resolved contract (spawn arg > agent-file
+  // definition), so an agent-file can declare `background: true` and be spawned
+  // detached without the caller passing it. `effectiveContract.background`
+  // already folds in `args.background`; the explicit OR keeps the path
+  // byte-identical if contract resolution was skipped (effectiveContract null).
+  const wantsBackground =
+    args.background === true || effectiveContract?.background === true;
+  if (wantsBackground && ctx.backgroundSubAgents instanceof Map) {
     // Cancel with the parent: forward the loop's abort signal so killing the
     // run doesn't orphan a detached child mid-LLM-call.
     subCtx._signal = subCtx._signal || ctx.signal || null;
@@ -6544,9 +6864,23 @@ export async function* agentLoop(messages, options) {
   // Optional OpenTelemetry recorder (TelemetryRecorder). When present, the loop
   // emits model/tool/retry spans + a per-run counter; when absent, zero cost.
   const recorder = options.recorder || null;
+  // Phase 5 run bookends — a stable runId lets envelope subscribers correlate
+  // every tool_call / tool_result / message / ended event back to one run.
+  // Minted BEFORE the tool context so hook envelopes can carry it as trace_id.
+  const runId =
+    options.runId ||
+    `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
   const toolContext = {
     hookDb: options.hookDb || null,
     skillLoader: options.skillLoader || _defaultSkillLoader,
+    // Hook-envelope tracing (P2 unified event bus): every settings-hook payload
+    // fired during this run carries trace_id = this run's id; a spawned child
+    // loop carries parent_id = the spawning run's id (threaded by
+    // spawn_sub_agent via hookParentTraceId), so a subagent's hook events
+    // correlate back to the parent trace. Null parent at the top level.
+    hookTraceId: runId,
+    hookParentId: options.hookParentTraceId || null,
     // Contract-driven skill allow-list (subagent capability INTERSECT). null =
     // unrestricted; [] = none; a list restricts run_skill/list_skills to those
     // ids/dirNames. Set by the spawn path from the resolved subagent contract.
@@ -6736,11 +7070,6 @@ export async function* agentLoop(messages, options) {
     });
   }
 
-  // Phase 5 run bookends — a stable runId lets envelope subscribers correlate
-  // every tool_call / tool_result / message / ended event back to one run.
-  const runId =
-    options.runId ||
-    `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   // Workflow-tracing attributes (Claude-Code 2.1.202): stamp the run id (and
   // an optional caller-provided workflow name) onto EVERY span this run emits,
   // so a collector can group one run's model/tool spans into one workflow.