chainlesschain 0.162.148 → 0.162.149

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 ────────────────────────────────────────────────
 //
@@ -514,6 +515,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
@@ -1302,6 +1305,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 +1358,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 +1498,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 +1761,126 @@ 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;
+
+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");
+    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 +1905,7 @@ async function executeToolInner(
     subAgentDepth = 0,
     subAgentBudget = null,
     interactiveApproval = false,
+    settingsHooks = null,
   },
 ) {
   const localToolDescriptor =
@@ -1769,6 +1958,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 +2024,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 +2077,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 +2100,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 +2132,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 +2158,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": {
@@ -2125,20 +2344,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,
@@ -2351,6 +2615,7 @@ async function executeToolInner(
           llmOptions,
           subAgentDepth,
           subAgentBudget,
+          settingsHooks,
         }),
       );
     }
@@ -2615,6 +2880,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 +3650,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 +5016,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 +5112,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 +5168,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 +5207,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 +5292,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
@@ -5064,7 +5510,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 +5780,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 +5861,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":