chainlesschain 0.162.148 → 0.162.150

package/src/runtime/agent-core.js

@@ -83,7 +83,8 @@ const { evaluateShellCommandPolicy } = sharedShellPolicy;
 const { evaluatePermissionRules } = sharedPermissionRules;
 const { collectHooks, umbrellaFor } = sharedSettingsHooks;
 const { runHooks: runCommandHooks } = sharedHookRunner;
-const { runObserveHooks } = sharedHookEvents;
+const { runObserveHooks, aggregateContext, partitionAsyncHooks } =
+  sharedHookEvents;
 
 // ─── Background shell tasks ────────────────────────────────────────────────
 //
@@ -220,6 +221,77 @@ export function killAllBackgroundShellTasks() {
   return killed;
 }
 
+// SYNCHRONOUS whole-tree kill for use inside a process 'exit' / signal handler,
+// where only synchronous work runs to completion (the async `spawn`/`taskkill`
+// in _killTask would be cut off the instant the process terminates, leaving the
+// grandchild orphaned). POSIX signals the process group with SIGKILL; Windows
+// uses spawnSync taskkill /T so the shell's children die too.
+function _killTaskSync(task) {
+  const child = task?.child;
+  if (!child || child.killed || task?.status !== "running") return false;
+  try {
+    if (process.platform === "win32") {
+      if (child.pid) {
+        spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+          windowsHide: true,
+        });
+      } else {
+        child.kill();
+      }
+    } else if (child.pid) {
+      // Negative pid → whole process group (requires the detached spawn above).
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch (_err) {
+        child.kill("SIGKILL");
+      }
+    } else {
+      child.kill("SIGKILL");
+    }
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Synchronously kill every still-running background shell task. Safe to call
+ * from a process 'exit' or signal handler (uses spawnSync/process.kill, not the
+ * async spawn path which a terminating process would cut off). This is the
+ * orphan-reclaim net for the paths the normal `finally` reaper can't cover: a
+ * Ctrl-C / SIGTERM unwinds no `finally`, so without it a backgrounded dev server
+ * outlives a killed `cc agent -p`.
+ * @returns {number} count of tasks signalled
+ */
+export function killAllBackgroundShellTasksSync() {
+  let killed = 0;
+  for (const task of _backgroundShellTasks.values()) {
+    if (_killTaskSync(task)) {
+      killed += 1;
+    }
+  }
+  return killed;
+}
+
+// Install a one-time process 'exit' net that synchronously reaps background
+// shell tasks. `finally` blocks (headless/REPL) already reap on normal
+// completion, but an explicit process.exit() elsewhere (serve shutdown, the
+// headless signal handler that converts Ctrl-C → exit) would otherwise leave a
+// backgrounded command orphaned. Installed lazily on the first background task,
+// so a process that never backgrounds anything pays nothing.
+let _bgExitReaperHooked = false;
+function _ensureBgExitReaper() {
+  if (_bgExitReaperHooked) return;
+  _bgExitReaperHooked = true;
+  process.once("exit", () => {
+    try {
+      killAllBackgroundShellTasksSync();
+    } catch {
+      /* best-effort teardown on exit */
+    }
+  });
+}
+
 // Idle-reap tuning (Claude-Code 2.1.193 "automatic memory-pressure reaping for
 // idle background shell commands"). A running task is a reap candidate when it
 // has produced no output for BG_IDLE_REAP_MS AND the system is under memory
@@ -323,16 +395,12 @@ async function runSettingsPreToolUseHooks(name, args, context, cwd) {
         ideResult: ide.result,
       };
     }
-    const confirm = context.permissionConfirm || context.shellConfirm || null;
-    const ok =
-      typeof confirm === "function"
-        ? await confirm({
-            tool: name,
-            args,
-            rule: `hook:${outcome.hook}`,
-            reason: outcome.reason || "a PreToolUse hook requests confirmation",
-          })
-        : false;
+    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 }
       : {
@@ -344,6 +412,87 @@ async function runSettingsPreToolUseHooks(name, args, context, cwd) {
   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) {
+  const matched = collectHooks(
+    context.settingsHooks,
+    "PermissionRequest",
+    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 outcome = runCommandHooks(matched, payload, {
+    cwd,
+    event: "PermissionRequest",
+  });
+  // 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
+ * prompting), then falls back to the injected confirmer with the identical
+ * arguments the call site would have passed. When no `PermissionRequest` hook
+ * matches this is byte-for-byte the previous `confirm(confirmArgs)` call, so
+ * every existing permission gate keeps its exact behaviour absent a hook.
+ * @returns {Promise<boolean>}
+ */
+async function requestInteractivePermission(
+  name,
+  args,
+  context,
+  cwd,
+  confirmArgs,
+) {
+  const verdict = runSettingsPermissionRequestHooks(
+    name,
+    args,
+    context,
+    cwd,
+    confirmArgs?.reason,
+  );
+  if (verdict.decision === "allow") return true;
+  if (verdict.decision === "deny") return false;
+  const confirm = context.permissionConfirm || context.shellConfirm || null;
+  return typeof confirm === "function" ? await confirm(confirmArgs) : false;
+}
+
 // ─── Tool definitions ────────────────────────────────────────────────────
 
 export const AGENT_TOOLS = getCodingAgentFunctionToolDefinitions();
@@ -514,6 +663,8 @@ Key behaviors:
 - For long-running commands (builds, full test suites, dev servers) set run_shell { run_in_background: true } to get a task_id back immediately, then poll output and completion with check_shell { task_id }. Kill a backgrounded server with check_shell { task_id, kill: true } when finished
 - When asked about git status, diff, log, or other repository operations, use the git tool instead of run_shell
 - 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.
 - 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
@@ -1079,16 +1230,12 @@ export async function executeTool(name, args, context = {}) {
       source: "settings rule",
     });
     if (ide) return ide.result;
-    const confirm = context.permissionConfirm || context.shellConfirm || null;
-    const ok =
-      typeof confirm === "function"
-        ? await confirm({
-            tool: name,
-            args,
-            rule: settingsVerdict.rule,
-            reason: `settings rule ${settingsVerdict.rule} requires confirmation`,
-          })
-        : false;
+    const ok = await requestInteractivePermission(name, args, context, cwd, {
+      tool: name,
+      args,
+      rule: settingsVerdict.rule,
+      reason: `settings rule ${settingsVerdict.rule} requires confirmation`,
+    });
     if (!ok) {
       return {
         error: `[Permission] Tool "${name}" requires confirmation (settings rule: ${settingsVerdict.rule}) but this run is non-interactive — denied. Do not retry; tell the user this action needs their approval.`,
@@ -1120,16 +1267,12 @@ export async function executeTool(name, args, context = {}) {
       await import("../lib/sensitive-file-guard.js");
     const sensReason = sensitiveFileReason(args.path);
     if (sensReason) {
-      const confirm = context.permissionConfirm || context.shellConfirm || null;
-      const ok =
-        typeof confirm === "function"
-          ? await confirm({
-              tool: name,
-              args,
-              rule: null,
-              reason: `sensitive file: ${sensReason}`,
-            })
-          : false;
+      const ok = await requestInteractivePermission(name, args, context, cwd, {
+        tool: name,
+        args,
+        rule: null,
+        reason: `sensitive file: ${sensReason}`,
+      });
       if (!ok) {
         return {
           error: `[Sensitive File] Writing "${args.path}" requires confirmation (${sensReason}) — denied. Add a settings allow rule to pre-authorize.`,
@@ -1152,16 +1295,12 @@ export async function executeTool(name, args, context = {}) {
     !planManager.isActive() &&
     isDangerousGitCommand(args?.command)
   ) {
-    const confirm = context.permissionConfirm || context.shellConfirm || null;
-    const ok =
-      typeof confirm === "function"
-        ? await confirm({
-            tool: name,
-            args,
-            rule: null,
-            reason: `destructive git command: git ${normalizeGitCommand(args.command)}`,
-          })
-        : false;
+    const ok = await requestInteractivePermission(name, args, context, cwd, {
+      tool: name,
+      args,
+      rule: null,
+      reason: `destructive git command: git ${normalizeGitCommand(args.command)}`,
+    });
     if (!ok) {
       return {
         error: `[Destructive Git] "git ${normalizeGitCommand(args.command)}" discards work irrecoverably and requires confirmation — denied. Add a settings allow rule to pre-authorize.`,
@@ -1196,17 +1335,18 @@ export async function executeTool(name, args, context = {}) {
         credReason = hit ? hit.reason : null;
       }
       if (credReason) {
-        const confirm =
-          context.permissionConfirm || context.shellConfirm || null;
-        const ok =
-          typeof confirm === "function"
-            ? await confirm({
-                tool: name,
-                args,
-                rule: null,
-                reason: `credential access: ${credReason}`,
-              })
-            : false;
+        const ok = await requestInteractivePermission(
+          name,
+          args,
+          context,
+          cwd,
+          {
+            tool: name,
+            args,
+            rule: null,
+            reason: `credential access: ${credReason}`,
+          },
+        );
         if (!ok) {
           const what =
             name === "read_file" ? `Reading "${args.path}"` : "This command";
@@ -1302,6 +1442,7 @@ export async function executeTool(name, args, context = {}) {
       subAgentDepth: context.subAgentDepth || 0,
       subAgentBudget: context.subAgentBudget || null,
       interactiveApproval: context.interactiveApproval || false,
+      settingsHooks: context.settingsHooks || null,
     });
   } catch (err) {
     if (hookDb) {
@@ -1354,24 +1495,36 @@ export async function executeTool(name, args, context = {}) {
     try {
       const matched = collectHooks(context.settingsHooks, "PostToolUse", name);
       if (matched && matched.length > 0) {
-        const outcome = runCommandHooks(
-          matched,
-          {
-            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),
+        // `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 = {
+          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,
+        };
+        if (sync.length > 0) {
+          const outcome = runCommandHooks(sync, payload, {
             cwd,
-            session_id: context.sessionId || null,
-          },
-          { cwd, event: "PostToolUse" },
-        );
-        if (outcome.decision === "block" && outcome.reason) {
-          toolResult.hookFeedback = outcome.reason;
+            event: "PostToolUse",
+          });
+          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 });
         }
       }
     } catch (_err) {
@@ -1482,6 +1635,58 @@ export function writeFileVerified(filePath, content, fsImpl = fs) {
   return { size: actual };
 }
 
+// ── Edit-concurrency (read-freshness) guard ──────────────────────────────
+//
+// Per-session map: resolved file path → the mtimeMs the agent last OBSERVED for
+// it (via read_file, or the write/edit it just made). If a file's on-disk mtime
+// is NEWER than that when the agent tries to edit it, an external process wrote
+// the file between the agent's read and its edit — so the edit is refused and
+// the agent is told to re-read, instead of clobbering the concurrent change on
+// top of a stale understanding. A file the agent never observed is NOT blocked
+// (first-touch / create stays frictionless). Disable with CC_EDIT_FRESHNESS=0.
+const _fileObservedMtimes = new Map();
+
+/** Record the current mtime of a file the agent just read or wrote. */
+function _recordFileObservation(filePath, fsImpl = fs) {
+  try {
+    _fileObservedMtimes.set(filePath, fsImpl.statSync(filePath).mtimeMs);
+  } catch {
+    /* best-effort — a stat failure just means no freshness baseline */
+  }
+}
+
+/**
+ * Return an error string when `filePath` changed on disk since the agent last
+ * observed it (external concurrent edit), else null (fresh, un-observed, or
+ * disabled).
+ */
+function _checkFileFreshness(filePath, fsImpl = fs) {
+  if (process.env.CC_EDIT_FRESHNESS === "0") return null;
+  const known = _fileObservedMtimes.get(filePath);
+  if (known === undefined) return null; // never observed → don't block
+  let current;
+  try {
+    current = fsImpl.statSync(filePath).mtimeMs;
+  } catch {
+    return null;
+  }
+  if (current > known) {
+    return (
+      `File changed on disk since you last read it: ${filePath}. Another ` +
+      `process modified it after your last read — re-read the file before ` +
+      `editing so your change is based on its current content (this guard ` +
+      `prevents silently clobbering a concurrent edit; set CC_EDIT_FRESHNESS=0 ` +
+      `to disable).`
+    );
+  }
+  return null;
+}
+
+/** Clear the read-freshness map (new session / tests). */
+export function _resetFileFreshness() {
+  _fileObservedMtimes.clear();
+}
+
 // Short, stable-ish id for a freshly inserted notebook cell (nbformat 4.5+).
 function _newNotebookCellId() {
   return Math.random().toString(36).slice(2, 10);
@@ -1693,6 +1898,139 @@ export function _ingestSearchOutput(output, ctx) {
 /**
  * Inner tool execution — no hooks, no plan-mode checks.
  */
+// ─── Shared code-intelligence (LSP) pool ──────────────────────────────────
+//
+// A language server is expensive to start (spawns a process + indexes the
+// project), so the `code_intelligence` tool reuses ONE warm CodeIntelligence
+// per project root across tool calls within a run. To avoid the resource-leak
+// trap (orphaned server processes / dangling timers), each root auto-disposes
+// after an idle window, and a process-exit hook is registered once as a
+// backstop. `coldStart:true` makes the first query per file wait for the
+// project to load; warmed queries return immediately.
+const _codeIntelPool = new Map(); // root -> { ci, idleTimer }
+const CODE_INTEL_IDLE_MS = 60_000;
+let _codeIntelExitHooked = false;
+
+export async function _getSharedCodeIntel(cwd) {
+  const root = path.resolve(cwd || process.cwd());
+  let entry = _codeIntelPool.get(root);
+  if (!entry) {
+    const { CodeIntelligence } =
+      await import("../lib/lsp/code-intelligence.js");
+    // Re-check AFTER the await: two concurrent callers (the parallel read-only
+    // batch runs several `code_intelligence` calls at once) both observed an
+    // empty pool before this `await import`, so without this guard both would
+    // construct a CodeIntelligence — each spawning its own language server — and
+    // the second `set` would orphan the first (leaked server process) while its
+    // stale idle-timer, still bound to `root`, later evicts the wrong (warm,
+    // in-use) entry. This is exactly the orphaned-server/dangling-timer trap the
+    // pool exists to prevent. Construction below has NO further await, so once
+    // one continuation wins the re-check the other reuses its entry — the window
+    // is fully closed.
+    entry = _codeIntelPool.get(root);
+    if (!entry) {
+      entry = {
+        ci: new CodeIntelligence({ projectRoot: root, coldStart: true }),
+        idleTimer: null,
+      };
+      _codeIntelPool.set(root, entry);
+      if (!_codeIntelExitHooked) {
+        _codeIntelExitHooked = true;
+        process.once("exit", () => {
+          for (const e of _codeIntelPool.values()) {
+            try {
+              e.ci.dispose();
+            } catch {
+              /* best-effort teardown on exit */
+            }
+          }
+        });
+      }
+    }
+  }
+  if (entry.idleTimer) clearTimeout(entry.idleTimer);
+  entry.idleTimer = setTimeout(() => {
+    _codeIntelPool.delete(root);
+    entry.ci.dispose().catch(() => {});
+  }, CODE_INTEL_IDLE_MS);
+  if (typeof entry.idleTimer.unref === "function") entry.idleTimer.unref();
+  return entry.ci;
+}
+
+/** Dispose every pooled language server now (used by tests + explicit shutdown). */
+export async function disposeSharedCodeIntel() {
+  const entries = [..._codeIntelPool.values()];
+  _codeIntelPool.clear();
+  for (const e of entries) {
+    if (e.idleTimer) clearTimeout(e.idleTimer);
+  }
+  await Promise.all(entries.map((e) => e.ci.dispose().catch(() => {})));
+}
+
+// Hard wall-clock cap so post-edit diagnostics never stall the agent: a cold
+// language server can take seconds to load a project on the FIRST edit; after
+// that the server is warm and answers in well under a second.
+const EDIT_DIAGNOSTICS_WALL_MS = 6000;
+
+/**
+ * Best-effort "did this edit introduce a new error?" check. Run after a
+ * successful workspace edit so the model sees fresh type/syntax errors in the
+ * SAME turn instead of discovering them on the next build (the plan's
+ * "编辑后执行增量诊断并将相关错误回喂 Agent"). Returns a compact array of
+ * error/warning diagnostics, or null.
+ *
+ * Zero cost when no language server is installed for the file (probes first,
+ * never cold-starts a server that isn't there) and fully bounded in time.
+ * Disable entirely with CC_EDIT_DIAGNOSTICS=0.
+ */
+async function _postEditDiagnostics(filePath, cwd) {
+  if (process.env.CC_EDIT_DIAGNOSTICS === "0") return null;
+  let hasServer = false;
+  try {
+    const { languageIdForFile, resolveServer } =
+      await import("../lib/lsp/lsp-server-registry.js");
+    const languageId = languageIdForFile(filePath);
+    if (!languageId) return null; // unsupported file type — no LSP, no cost
+    hasServer = Boolean(
+      resolveServer(languageId, path.resolve(cwd || process.cwd())),
+    );
+  } catch {
+    return null;
+  }
+  if (!hasServer) return null;
+
+  const query = (async () => {
+    try {
+      const ci = await _getSharedCodeIntel(cwd);
+      const res = await ci.refreshFile(filePath, { timeoutMs: 3000 });
+      if (!res || res.available === false) return null;
+      const diags = (res.diagnostics || []).filter(
+        (d) => d.severity === "error" || d.severity === "warning",
+      );
+      return diags.length ? diags.slice(0, 20) : null;
+    } catch {
+      return null;
+    }
+  })();
+
+  let capTimer;
+  const cap = new Promise((resolve) => {
+    capTimer = setTimeout(() => resolve(null), EDIT_DIAGNOSTICS_WALL_MS);
+    if (typeof capTimer.unref === "function") capTimer.unref();
+  });
+  try {
+    return await Promise.race([query, cap]);
+  } finally {
+    clearTimeout(capTimer);
+  }
+}
+
+/** Merge post-edit diagnostics into a successful edit result (no-op if none). */
+async function _withPostEditDiagnostics(result, filePath, cwd) {
+  const newDiagnostics = await _postEditDiagnostics(filePath, cwd);
+  return newDiagnostics ? { ...result, newDiagnostics } : result;
+}
+
 async function executeToolInner(
   name,
   args,
@@ -1717,6 +2055,7 @@ async function executeToolInner(
     subAgentDepth = 0,
     subAgentBudget = null,
     interactiveApproval = false,
+    settingsHooks = null,
   },
 ) {
   const localToolDescriptor =
@@ -1769,6 +2108,9 @@ async function executeToolInner(
         });
       }
       const content = fs.readFileSync(filePath, "utf8");
+      // Record the mtime so a later edit can detect an external change that
+      // happened between this read and the edit (read-freshness guard).
+      _recordFileObservation(filePath);
       // Jupyter notebooks: render a compact cell listing (index/id/type/source,
       // outputs summarized) so the model can find cells for notebook_edit
       // without ingesting raw JSON / base64 output blobs. `raw:true` returns the
@@ -1832,16 +2174,25 @@ async function executeToolInner(
     case "write_file": {
       const filePath = path.resolve(cwd, args.path);
       const dir = path.dirname(filePath);
+      // Overwriting an existing file: refuse if it changed on disk since the
+      // agent last observed it (external concurrent edit).
+      if (fs.existsSync(filePath)) {
+        const stale = _checkFileFreshness(filePath);
+        if (stale) return attachDescriptor({ error: stale });
+      }
       if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
       }
       const wrote = writeFileVerified(filePath, args.content);
       if (wrote.error) return attachDescriptor({ error: wrote.error });
-      return attachDescriptor({
-        success: true,
-        path: filePath,
-        size: wrote.size,
-      });
+      _recordFileObservation(filePath);
+      return attachDescriptor(
+        await _withPostEditDiagnostics(
+          { success: true, path: filePath, size: wrote.size },
+          filePath,
+          cwd,
+        ),
+      );
     }
 
     case "notebook_edit": {
@@ -1876,6 +2227,8 @@ async function executeToolInner(
       if (typeof args.new_string !== "string") {
         return attachDescriptor({ error: "new_string must be a string" });
       }
+      const staleEdit = _checkFileFreshness(filePath);
+      if (staleEdit) return attachDescriptor({ error: staleEdit });
       const content = fs.readFileSync(filePath, "utf8");
       const replaceAll = args.replace_all === true;
       const { count, newContent } = applyLiteralEdit(
@@ -1897,12 +2250,19 @@ async function executeToolInner(
       }
       const wrote = writeFileVerified(filePath, newContent);
       if (wrote.error) return attachDescriptor({ error: wrote.error });
-      return attachDescriptor({
-        success: true,
-        path: filePath,
-        size: wrote.size,
-        replaced: replaceAll ? count : 1,
-      });
+      _recordFileObservation(filePath);
+      return attachDescriptor(
+        await _withPostEditDiagnostics(
+          {
+            success: true,
+            path: filePath,
+            size: wrote.size,
+            replaced: replaceAll ? count : 1,
+          },
+          filePath,
+          cwd,
+        ),
+      );
     }
 
     case "edit_file_hashed": {
@@ -1922,6 +2282,8 @@ async function executeToolInner(
       if (typeof args.new_line !== "string") {
         return attachDescriptor({ error: "new_line must be a string" });
       }
+      const staleHashed = _checkFileFreshness(filePath);
+      if (staleHashed) return attachDescriptor({ error: staleHashed });
       const original = fs.readFileSync(filePath, "utf8");
       const result = replaceByHash(original, {
         anchorHash: args.anchor_hash,
@@ -1946,13 +2308,20 @@ async function executeToolInner(
       }
       const wrote = writeFileVerified(filePath, result.content);
       if (wrote.error) return attachDescriptor({ error: wrote.error });
-      return attachDescriptor({
-        success: true,
-        path: filePath,
-        size: wrote.size,
-        lineNumber: result.lineNumber,
-        previousContent: result.previousContent,
-      });
+      _recordFileObservation(filePath);
+      return attachDescriptor(
+        await _withPostEditDiagnostics(
+          {
+            success: true,
+            path: filePath,
+            size: wrote.size,
+            lineNumber: result.lineNumber,
+            previousContent: result.previousContent,
+          },
+          filePath,
+          cwd,
+        ),
+      );
     }
 
     case "run_shell": {
@@ -2108,6 +2477,9 @@ async function executeToolInner(
           task.endedAt = new Date().toISOString();
         }
         _backgroundShellTasks.set(id, task);
+        // Arm the process-exit net so a Ctrl-C / hard exit can't orphan this
+        // task (the normal `finally` reaper is bypassed by signals).
+        _ensureBgExitReaper();
         return attachDescriptor(
           {
             background: true,
@@ -2125,20 +2497,65 @@ async function executeToolInner(
       if (sandbox) {
         const { executeSandboxedShell, sandboxSummary } =
           await import("../lib/agent-sandbox.js");
-        const result = executeSandboxedShell(args.command, sandbox, {
-          cwd: args.cwd || cwd,
-          timeout: _resolveShellTimeout(args.timeout),
-          maxBuffer: 1024 * 1024,
-          env: {
-            CLAUDECODE: "1",
-            ...(sessionId
-              ? {
-                  CC_SESSION_ID: String(sessionId),
-                  CLAUDE_CODE_SESSION_ID: String(sessionId),
-                }
-              : {}),
-          },
-        });
+        // Domain-restricted networking is ENFORCED by routing the sandboxed
+        // process's egress through a local filtering proxy (see
+        // sandbox-egress-proxy.js). Start it only when the policy actually
+        // restricts domains and network is on; tear it down after the command.
+        const sboxPolicy = sandbox.policy || {};
+        const needsEgress =
+          sandbox.network === true &&
+          (sboxPolicy.allowedDomains?.length || 0) +
+            (sboxPolicy.deniedDomains?.length || 0) >
+            0;
+        let egressProxy = null;
+        let proxyHandle = null;
+        if (needsEgress) {
+          try {
+            const { createEgressProxy } =
+              await import("../lib/sandbox-egress-proxy.js");
+            proxyHandle = createEgressProxy(
+              {
+                allowedDomains: sboxPolicy.allowedDomains || [],
+                deniedDomains: sboxPolicy.deniedDomains || [],
+                allowPrivate: sboxPolicy.allowPrivate === true,
+              },
+              { bindHost: "0.0.0.0" }, // reachable from the container/netns
+            );
+            const listened = await proxyHandle.listen();
+            egressProxy = { port: listened.port };
+          } catch {
+            // If the proxy can't start, leave egressProxy null so the sandbox
+            // fails closed (refuses) rather than running without enforcement.
+            proxyHandle = null;
+            egressProxy = null;
+          }
+        }
+        let result;
+        try {
+          result = executeSandboxedShell(args.command, sandbox, {
+            cwd: args.cwd || cwd,
+            timeout: _resolveShellTimeout(args.timeout),
+            maxBuffer: 1024 * 1024,
+            egressProxy,
+            env: {
+              CLAUDECODE: "1",
+              ...(sessionId
+                ? {
+                    CC_SESSION_ID: String(sessionId),
+                    CLAUDE_CODE_SESSION_ID: String(sessionId),
+                  }
+                : {}),
+            },
+          });
+        } finally {
+          if (proxyHandle) {
+            try {
+              await proxyHandle.close();
+            } catch {
+              /* best-effort teardown */
+            }
+          }
+        }
         const common = {
           sandbox: sandboxSummary(sandbox),
           shellCommandPolicy: shellPolicy,
@@ -2199,6 +2616,14 @@ async function executeToolInner(
         return attachDescriptor(
           {
             error: err.message.substring(0, 2000),
+            // Surface stdout too: a failing command (test runner / linter /
+            // build) usually prints WHAT failed to stdout and only the summary
+            // to stderr, so dropping it on non-zero exit blinds the agent to the
+            // actual failure. Only attach it when there IS output (a timeout with
+            // no output keeps the field absent), mirroring the success path.
+            ...(err.stdout
+              ? { stdout: String(err.stdout).substring(0, 30000) }
+              : {}),
             stderr: (err.stderr || "").substring(0, 2000),
             exitCode: err.status,
             shellCommandPolicy: shellPolicy,
@@ -2351,6 +2776,7 @@ async function executeToolInner(
           llmOptions,
           subAgentDepth,
           subAgentBudget,
+          settingsHooks,
         }),
       );
     }
@@ -2615,6 +3041,95 @@ async function executeToolInner(
       return attachDescriptor(isContent ? { matches: hits } : { files: hits });
     }
 
+    case "code_intelligence": {
+      const action = String(args.action || "").trim();
+      const positionActions = new Set([
+        "definition",
+        "references",
+        "hover",
+        "rename_preview",
+      ]);
+      // Validate up front so the model gets a precise correction instead of a
+      // cryptic crash deep in the LSP layer.
+      if (action !== "workspace_symbols" && !args.file) {
+        return attachDescriptor({
+          error: `code_intelligence action "${action}" requires "file".`,
+        });
+      }
+      if (
+        positionActions.has(action) &&
+        (args.line == null || args.col == null)
+      ) {
+        return attachDescriptor({
+          error: `code_intelligence action "${action}" requires 1-based "line" and "col".`,
+        });
+      }
+      if (action === "workspace_symbols" && !args.query) {
+        return attachDescriptor({
+          error: `code_intelligence action "workspace_symbols" requires "query".`,
+        });
+      }
+      if (action === "rename_preview" && !args.new_name) {
+        return attachDescriptor({
+          error: `code_intelligence action "rename_preview" requires "new_name".`,
+        });
+      }
+      const ci = await _getSharedCodeIntel(cwd);
+      const file = args.file ? path.resolve(cwd, args.file) : null;
+      let res;
+      try {
+        switch (action) {
+          case "definition":
+            res = await ci.definition(file, args.line, args.col);
+            break;
+          case "references":
+            res = await ci.references(file, args.line, args.col);
+            break;
+          case "hover":
+            res = await ci.hover(file, args.line, args.col);
+            break;
+          case "document_symbols":
+            res = await ci.documentSymbols(file);
+            break;
+          case "workspace_symbols":
+            res = await ci.workspaceSymbols(String(args.query));
+            break;
+          case "diagnostics":
+            res = await ci.diagnostics(file);
+            break;
+          case "rename_preview":
+            res = await ci.renamePreview(
+              file,
+              args.line,
+              args.col,
+              args.new_name,
+            );
+            break;
+          default:
+            return attachDescriptor({
+              error:
+                `Unknown code_intelligence action "${action}". Valid: definition, ` +
+                `references, hover, document_symbols, workspace_symbols, ` +
+                `diagnostics, rename_preview.`,
+            });
+        }
+      } catch (err) {
+        return attachDescriptor({
+          error: `code_intelligence failed: ${err.message}`,
+        });
+      }
+      // No language server installed for this file — tell the agent to fall back
+      // rather than looping on an empty result.
+      if (res && res.available === false) {
+        return attachDescriptor({
+          unavailable: true,
+          reason: res.reason,
+          hint: "No language server available — use search_files / read_file instead.",
+        });
+      }
+      return attachDescriptor(res);
+    }
+
     case "list_dir": {
       const dirPath = args.path ? path.resolve(cwd, args.path) : cwd;
       if (!fs.existsSync(dirPath)) {
@@ -3296,6 +3811,39 @@ async function _executeSpawnSubAgent(args, ctx) {
   const parentSessionId = ctx.sessionId || null;
   const interaction = ctx.interaction || null;
 
+  // settings.json SubagentStart hooks (Claude-Code parity): fire BEFORE the
+  // sub-agent runs, so a policy hook can VETO the spawn (`block`) or INJECT
+  // extra context that gets prepended to the child's inherited context. This is
+  // the mirror of the existing SubagentStop fire (which runs after the summary
+  // returns). Best-effort — a hook error never blocks the spawn.
+  if (ctx.settingsHooks) {
+    try {
+      const startOutcome = runObserveHooks(
+        ctx.settingsHooks,
+        "SubagentStart",
+        {
+          session_id: parentSessionId,
+          role: role || args.agent || null,
+          subagent_task: String(task || "").substring(0, 2000),
+        },
+        { cwd: ctx.cwd },
+      );
+      if (startOutcome.decision === "block" && startOutcome.reason) {
+        return {
+          error: `spawn_sub_agent blocked by SubagentStart hook: ${startOutcome.reason}`,
+        };
+      }
+      const injected = aggregateContext(startOutcome.results);
+      if (injected) {
+        resolvedContext = resolvedContext
+          ? `${resolvedContext}\n---\n${injected}`
+          : injected;
+      }
+    } catch (_err) {
+      // SubagentStart hooks are best-effort — never break the spawn.
+    }
+  }
+
   // Inherit the parent's provider / base-url / key; a named subagent's `model:`
   // frontmatter (mdModel) overrides just the model, else keep the parent's.
   const parentLlm = ctx.llmOptions || {};
@@ -4629,6 +5177,7 @@ export function _normalizeAnthropicResponse(data) {
 const _CHECKPOINT_READ_ONLY = new Set([
   "read_file",
   "search_files",
+  "code_intelligence",
   "list_dir",
   "list_skills",
   "search_sessions",
@@ -4724,6 +5273,54 @@ async function _getAutoCompactor(options) {
   return compressor;
 }
 
+/**
+ * Run `fn` inside an OpenTelemetry span when `options.recorder` is attached,
+ * else run it bare (zero overhead on the un-instrumented path). `onResult`
+ * gets (span, result) to stamp result-derived attributes (token usage, tool
+ * status). An exception is recorded on the span (category `errCategory`) and
+ * re-thrown so the loop's own error handling is unchanged. Kept dependency-free
+ * — the recorder is the OTel-shaped TelemetryRecorder passed in by the caller
+ * (eval / a future `--otlp` agent flag); the real agent loop now EMITS
+ * model/tool/retry spans, not just eval.
+ */
+async function _withSpan(recorder, name, attrs, fn, onResult, errCategory) {
+  if (!recorder || typeof recorder.startSpan !== "function") return fn();
+  const span = recorder.startSpan(name, attrs);
+  try {
+    const r = await fn();
+    if (onResult) {
+      try {
+        onResult(span, r);
+      } catch {
+        /* attribute stamping is best-effort */
+      }
+    }
+    span.end();
+    return r;
+  } catch (err) {
+    try {
+      span.recordException(err, errCategory || "error");
+      span.end();
+    } catch {
+      /* span teardown is best-effort */
+    }
+    throw err;
+  }
+}
+
+/** Normalize the varied provider usage shapes into input/output/cache tokens. */
+function _usageTokens(usage) {
+  if (!usage || typeof usage !== "object") return null;
+  const input = usage.prompt_tokens ?? usage.input_tokens ?? null;
+  const output = usage.completion_tokens ?? usage.output_tokens ?? null;
+  const cacheRead =
+    usage.cache_read_input_tokens ??
+    usage.prompt_tokens_details?.cached_tokens ??
+    null;
+  const cacheWrite = usage.cache_creation_input_tokens ?? null;
+  return { input, output, cacheRead, cacheWrite };
+}
+
 export async function* agentLoop(messages, options) {
   // Shared iteration budget — replaces hardcoded MAX_ITERATIONS.
   // When options.iterationBudget is provided (e.g. from parent agent),
@@ -4732,6 +5329,9 @@ export async function* agentLoop(messages, options) {
     await import("../lib/iteration-budget.js");
   const budget = options.iterationBudget || new IterationBudget();
   const signal = options.signal || null;
+  // 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;
   const toolContext = {
     hookDb: options.hookDb || null,
     skillLoader: options.skillLoader || _defaultSkillLoader,
@@ -4768,6 +5368,10 @@ export async function* agentLoop(messages, options) {
     permissionRules: options.permissionRules || null,
     permissionConfirm: options.permissionConfirm || null,
     settingsHooks: options.settingsHooks || null,
+    // Async-hook supervisor (REPL-owned): lets PostToolUse `async:true` hooks
+    // run fire-and-forget instead of blocking the tool loop. Optional — when
+    // absent, async PostToolUse hooks are simply skipped (never run sync).
+    hookSupervisor: options.hookSupervisor || null,
     autoCheckpoint: options.autoCheckpoint || false,
     checkpointSession:
       options.checkpointSession || options.sessionId || "agent",
@@ -4849,6 +5453,9 @@ export async function* agentLoop(messages, options) {
       await import("../lib/runnable-provider.js");
     llmCall = makeRunnableProviderFallback(llmCall, {
       onFallback: ({ from, to, reason, fromModel, toModel }) => {
+        // Telemetry: a provider/model fallback is a reliability signal — count
+        // it (keyed by reason) so a run's OTLP export shows retry/fallback rate.
+        if (recorder) recorder.counter("agent.model.fallback", 1, { reason });
         // Switching VENDORS (or relabelling via baseUrl) must NEVER be silent —
         // a user who configured volcengine deserves to know it ran on another
         // provider/model. Build a human message and hand it to the driver's
@@ -4994,10 +5601,22 @@ export async function* agentLoop(messages, options) {
               reason: preCompactReason,
             };
           }
+          // Auto-pin (OPT-IN): when enabled, the original task (first user turn)
+          // is pinned so compaction can't drop it. Off by default → no predicate
+          // is passed and compaction is byte-identical to before.
+          let pinOpts = {};
+          if (options.autoPin) {
+            const { buildAutoPinPredicate } = await import("./auto-pin.js");
+            const isPinned = buildAutoPinPredicate(messages, options.autoPin);
+            if (isPinned) pinOpts = { isPinned };
+          }
           const { messages: compacted, stats } =
             !needFull || preCompactBlocked
               ? { messages, stats: { saved: 0 } }
-              : await compactor.compress(messages, { preserveToolPairs: true });
+              : await compactor.compress(messages, {
+                  preserveToolPairs: true,
+                  ...pinOpts,
+                });
           if (stats.saved > 0 && compacted.length < messages.length) {
             messages.splice(0, messages.length, ...compacted);
             // Persist the compaction so a later --resume rebuilds from the
@@ -5064,7 +5683,38 @@ export async function* agentLoop(messages, options) {
       }
     }
 
-    const result = await llmCall(callMessages, options);
+    const result = await _withSpan(
+      recorder,
+      "agent.model",
+      {
+        "gen_ai.system": options.provider || "ollama",
+        "gen_ai.request.model": options.model || "unknown",
+        "agent.iteration": budget.consumed,
+      },
+      () => llmCall(callMessages, options),
+      (span, r) => {
+        const t = _usageTokens(r?.usage);
+        if (t) {
+          if (t.input != null)
+            span.setAttribute("gen_ai.usage.input_tokens", t.input);
+          if (t.output != null)
+            span.setAttribute("gen_ai.usage.output_tokens", t.output);
+          // Cache read/write tokens — the prompt-caching hit rate the plan's
+          // reliability telemetry cares about.
+          if (t.cacheRead != null)
+            span.setAttribute("gen_ai.usage.cache_read_tokens", t.cacheRead);
+          if (t.cacheWrite != null)
+            span.setAttribute("gen_ai.usage.cache_write_tokens", t.cacheWrite);
+        }
+        span.setAttribute(
+          "agent.has_tool_calls",
+          Array.isArray(r?.message?.tool_calls) &&
+            r.message.tool_calls.length > 0,
+        );
+      },
+      "model_error",
+    );
+    if (recorder) recorder.counter("agent.model.calls", 1);
     throwIfAborted(signal);
     const msg = result?.message;
 
@@ -5303,11 +5953,24 @@ export async function* agentLoop(messages, options) {
       let toolResult;
       let toolError = null;
       try {
-        toolResult = await executeTool(toolName, toolArgs, toolContext);
+        toolResult = await _withSpan(
+          recorder,
+          "agent.tool",
+          { "tool.name": toolName },
+          () => executeTool(toolName, toolArgs, toolContext),
+          (span, r) => {
+            span.setAttribute(
+              "tool.is_error",
+              !!(r && typeof r === "object" && r.error),
+            );
+          },
+          "tool_error",
+        );
       } catch (err) {
         toolResult = { error: err.message };
         toolError = err.message;
       }
+      if (recorder) recorder.counter("agent.tool.calls", 1);
 
       throwIfAborted(signal);
 
@@ -5371,6 +6034,10 @@ export function formatToolArgs(name, args) {
       return args.command;
     case "search_files":
       return args.pattern;
+    case "code_intelligence":
+      return args.action === "workspace_symbols"
+        ? `${args.action} ${args.query || ""}`.trim()
+        : `${args.action} ${args.file || ""}${args.line != null ? `:${args.line}:${args.col}` : ""}`.trim();
     case "list_dir":
       return args.path || ".";
     case "run_skill":