chainlesschain 0.166.22 → 0.166.25

package/src/runtime/agent-core.js

@@ -16,11 +16,14 @@
 
 import fs from "fs";
 import path from "path";
+import { buildReadFilePage } from "../lib/read-file-page.js";
+import { ReadFileLoopGuard } from "../lib/read-file-loop-guard.js";
 import broker from "../lib/process-execution-broker/index.js";
 import os from "os";
 import { createHash, randomUUID } from "node:crypto";
 import skillInvocationReceipt from "@chainlesschain/session-core/skill-invocation-receipt";
 import { isProxy } from "node:util/types";
+import { captureAgentEvolutionIngress } from "../lib/evolution/agent-evolution-ingress.js";
 
 const { startSkillInvocation, settleSkillInvocation } = skillInvocationReceipt;
 import sharedCodingAgentPolicy from "./coding-agent-policy.cjs";
@@ -1084,7 +1087,7 @@ Key behaviors:
 - When asked to run/test something, use run_shell to execute it
 - 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
+- When asked about files or code, use search_files to locate relevant sections, then read_file with offset/limit. Follow nextRead for large files. Reuse unchanged content already in context instead of repeatedly reading the same page; re-read when the file changes or the earlier content is no longer available.
 - 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).
@@ -3573,6 +3576,7 @@ export async function executeTool(name, args, context = {}) {
       skillAllowlist: context.skillAllowlist ?? null,
       skillOutcomeIndex: context.skillOutcomeIndex,
       skillVectorAuthority: context.skillVectorAuthority,
+      skillRetrievalRevocationReader: context.skillRetrievalRevocationReader,
       cwd,
       parentMessages: context.parentMessages,
       interaction: context.interaction,
@@ -3628,6 +3632,7 @@ export async function executeTool(name, args, context = {}) {
       subAgentBudget: context.subAgentBudget || null,
       sessionBudget: context.sessionBudget || null,
       hostResourceBudget: context.hostResourceBudget || null,
+      readFileCache: context.readFileCache || null,
       // Effective contract of THIS loop (parent ceiling for a nested spawn) +
       // the MCP tool definitions this loop exposes (inheritable by a spawn).
       subAgentContract: context.subAgentContract || null,
@@ -5118,6 +5123,7 @@ async function executeToolInner(
     skillAllowlist = null,
     skillOutcomeIndex,
     skillVectorAuthority,
+    skillRetrievalRevocationReader,
     cwd,
     parentMessages,
     interaction,
@@ -5171,6 +5177,7 @@ async function executeToolInner(
     backgroundUsageFailureState = null,
     toolAdmission = null,
     hostResourceBudget = null,
+    readFileCache = null,
     unattendedActionPolicy = null,
     managedCheckpoint = false,
     fileMutationScope = null,
@@ -5239,11 +5246,37 @@ async function executeToolInner(
       }
       // A clear, self-correcting error beats the cryptic "EISDIR: illegal
       // operation on a directory" that readFileSync throws on a directory.
-      if (fs.statSync(filePath).isDirectory()) {
+      const fileStat = fs.statSync(filePath);
+      if (fileStat.isDirectory()) {
         return attachDescriptor({
           error: `Path is a directory, not a file: ${filePath}. Use list_dir to see its contents.`,
         });
       }
+      const fileVersion = `${fileStat.size}:${fileStat.mtimeMs}:${fileStat.ctimeMs}`;
+      const cacheKey = JSON.stringify([
+        filePath,
+        args.offset ?? null,
+        args.limit ?? null,
+        args.column ?? null,
+        args.hashed === true,
+        args.raw === true,
+      ]);
+      const cached = readFileCache?.get(cacheKey);
+      if (cached?.fileVersion === fileVersion) {
+        // All permission checks ran before this point. A fresh stat still
+        // invalidates changed/deleted files; cache only bounded pages per run.
+        _recordFileObservation(filePath);
+        readFileCache.delete(cacheKey);
+        readFileCache.set(cacheKey, cached);
+        return attachDescriptor(
+          await _withSubtreeInstructions(
+            structuredClone(cached.page),
+            filePath,
+            cwd,
+            subtreeInstructionScope,
+          ),
+        );
+      }
       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).
@@ -5252,69 +5285,32 @@ async function executeToolInner(
       // outputs summarized) so the model can find cells for notebook_edit
       // without ingesting raw JSON / base64 output blobs. `raw:true` returns the
       // underlying JSON. Non-.ipynb reads are unchanged.
-      if (args.raw !== true && /\.ipynb$/i.test(filePath)) {
-        const nbView = renderNotebook(content);
-        if (nbView) {
-          return attachDescriptor(
-            nbView.length > 50000
-              ? {
-                  content: nbView.substring(0, 50000) + "\n...(truncated)",
-                  size: nbView.length,
-                  notebook: true,
-                }
-              : { content: nbView, notebook: true },
-          );
-        }
-      }
+      const nbView =
+        args.raw !== true && /\.ipynb$/i.test(filePath)
+          ? renderNotebook(content)
+          : null;
       // Hashline mode: prefix each line with a 6-char content hash tag
       // so downstream edit_file_hashed calls can anchor by hash.
-      let rendered = args.hashed === true ? annotateLines(content) : content;
-
-      // Line-range slice (Claude-Code Read offset/limit parity): `offset` is the
-      // 1-based first line, `limit` the max line count — so a file larger than
-      // the size cap can be paged through instead of being stuck at its head.
-      // Coerces numeric strings the model may emit ("10" → 10).
-      const toPos = (v) => {
-        const n = typeof v === "number" ? v : parseInt(v, 10);
-        return Number.isInteger(n) && n > 0 ? n : null;
-      };
-      const offset = toPos(args.offset);
-      const limit = toPos(args.limit);
-      let range = null;
-      if (offset || limit) {
-        const lines = rendered.split("\n");
-        const start = offset ? offset - 1 : 0;
-        const end = limit != null ? start + limit : lines.length;
-        rendered = lines.slice(start, end).join("\n");
-        range = {
-          startLine: Math.min(start + 1, lines.length),
-          endLine: Math.min(end, lines.length),
-          totalLines: lines.length,
-        };
-      }
-
-      if (rendered.length > 50000) {
-        return attachDescriptor(
-          await _withSubtreeInstructions(
-            {
-              content: rendered.substring(0, 50000) + "\n...(truncated)",
-              size: rendered.length,
-              hashed: args.hashed === true,
-              ...(range ? { range } : {}),
-            },
-            filePath,
-            cwd,
-            subtreeInstructionScope,
-          ),
-        );
+      const rendered =
+        nbView || (args.hashed === true ? annotateLines(content) : content);
+      const page = buildReadFilePage(rendered, args, {
+        filePath,
+        fileVersion,
+        maxChars: MAX_TOOL_RESULT_CHARS,
+      });
+      if (nbView) page.notebook = true;
+      if (readFileCache && !page.error) {
+        readFileCache.delete(cacheKey);
+        readFileCache.set(cacheKey, {
+          fileVersion,
+          page: structuredClone(page),
+        });
+        while (readFileCache.size > 8)
+          readFileCache.delete(readFileCache.keys().next().value);
       }
       return attachDescriptor(
         await _withSubtreeInstructions(
-          {
-            content: rendered,
-            hashed: args.hashed === true,
-            ...(range ? { range } : {}),
-          },
+          page,
           filePath,
           cwd,
           subtreeInstructionScope,
@@ -8283,6 +8279,7 @@ async function executeToolInner(
           target: { os: process.platform },
           vectorScores: vector?.scores ?? null,
           outcomeMetrics: outcomeAuthority.metrics,
+          revocationReader: skillRetrievalRevocationReader ?? null,
           topK: Math.min(64, Math.max(1, skills.length)),
         });
         const byDigest = new Map(
@@ -9326,6 +9323,46 @@ export function capToolResultString(serialized, max = MAX_TOOL_RESULT_CHARS) {
   );
 }
 
+/** Avoid injecting the same file page twice while its original is still visible. */
+export function toolResultForModel(tool, result, messages) {
+  const serialized = capToolResultString(safeStringifyToolResult(result));
+  if (
+    tool !== "read_file" ||
+    result?.error ||
+    !result?.path ||
+    !result.content ||
+    result.subtreeInstructions?.length
+  ) {
+    return serialized;
+  }
+  const previous = messages.find((message) => {
+    if (message.role !== "tool" || typeof message.content !== "string")
+      return false;
+    try {
+      const prior = JSON.parse(message.content.split("\n\n[Budget ")[0]);
+      return (
+        prior.path === result.path &&
+        prior.fileVersion === result.fileVersion &&
+        prior.content === result.content &&
+        prior.hashed === result.hashed &&
+        JSON.stringify(prior.range) === JSON.stringify(result.range)
+      );
+    } catch {
+      return false;
+    }
+  });
+  if (!previous) return serialized;
+  return JSON.stringify({
+    path: result.path,
+    alreadyRead: true,
+    previousToolCallId: previous.tool_call_id,
+    readAt: result.toolTelemetryRecord?.timestamp,
+    ...(result.range ? { range: result.range } : {}),
+    ...(result.nextRead ? { nextRead: result.nextRead } : {}),
+    hint: "This unchanged file page is already present in the earlier tool result. Use that content to continue the task. For more content, use nextRead or search_files for a different section; do not repeat this same read.",
+  });
+}
+
 /**
  * Serialize a tool result for the transcript without ever throwing. A plain
  * `JSON.stringify` throws on a circular reference, a BigInt, or a value whose
@@ -10730,6 +10767,10 @@ function _openAIProviderRequestReceipt(response, data, clientRequestId) {
  * @returns {Promise<object>} response with .message
  */
 export async function chatWithTools(rawMessages, options) {
+  const evolutionIngress =
+    options.evolutionIngress == null
+      ? null
+      : captureAgentEvolutionIngress(options.evolutionIngress);
   const {
     provider,
     model,
@@ -10771,13 +10812,22 @@ export async function chatWithTools(rawMessages, options) {
   const lastUserMsg = [...providerMessages]
     .reverse()
     .find((m) => m.role === "user");
-  const messages =
+  let messages =
     ce && !canonicalPlan
       ? ce.buildOptimizedMessages(providerMessages, {
           userQuery: lastUserMsg?.content,
         })
       : providerMessages;
 
+  if (evolutionIngress !== null) {
+    const projected = await evolutionIngress.prepareModelRequest({
+      messages,
+      tools,
+    });
+    messages = projected.messages;
+    tools = projected.tools;
+  }
+
   throwIfAborted(signal);
 
   if (provider === "ollama") {
@@ -12889,7 +12939,26 @@ function _instrumentAutoCompactorUsage(compactor, options) {
  * loaded — callers treat that as "don't compact". Cached (including null) so we
  * import once per run, not once per iteration.
  */
+const evolutionAutoCompactors = new WeakMap();
+
 async function _getAutoCompactor(options) {
+  const evolutionIngress =
+    options.evolutionIngress == null
+      ? null
+      : captureAgentEvolutionIngress(options.evolutionIngress);
+  if (
+    evolutionIngress !== null &&
+    (typeof options.compactionLlmQuery === "function" ||
+      (options._autoCompactor != null &&
+        evolutionAutoCompactors.get(options._autoCompactor) !==
+          evolutionIngress))
+  ) {
+    const error = new TypeError(
+      "Evolution auto-compaction requires the canonical model transport and owned compressor",
+    );
+    error.code = "CC_AGENT_EVOLUTION_INGRESS_FAILED";
+    throw error;
+  }
   if (Object.prototype.hasOwnProperty.call(options, "_autoCompactor")) {
     return _instrumentAutoCompactorUsage(options._autoCompactor, options);
   }
@@ -12983,8 +13052,11 @@ async function _getAutoCompactor(options) {
     }
   } catch (error) {
     if (canonicalRequired) throw error;
+    if (error?.code === "CC_AGENT_EVOLUTION_INGRESS_FAILED") throw error;
     compressor = null;
   }
+  if (evolutionIngress !== null && compressor !== null)
+    evolutionAutoCompactors.set(compressor, evolutionIngress);
   try {
     options._autoCompactor = compressor;
   } catch {
@@ -13207,6 +13279,20 @@ function permissionDecision(callId, tool, result) {
 }
 
 export async function* agentLoop(messages, options) {
+  const configuredChatFn = options.chatFn;
+  const evolutionIngress =
+    options.evolutionIngress == null
+      ? null
+      : captureAgentEvolutionIngress(options.evolutionIngress);
+  let llmCall = configuredChatFn || chatWithTools;
+  if (evolutionIngress !== null && configuredChatFn) {
+    const { captureCanonicalFallbackChatFn } =
+      await import("./fallback-model.js");
+    llmCall = captureCanonicalFallbackChatFn(
+      configuredChatFn,
+      evolutionIngress,
+    );
+  }
   // Shared iteration budget — replaces hardcoded MAX_ITERATIONS.
   // When options.iterationBudget is provided (e.g. from parent agent),
   // the same budget instance is shared, so parent+child consume from one pool.
@@ -13273,10 +13359,12 @@ export async function* agentLoop(messages, options) {
     options.mcpConflictScheduler || createMcpConflictScheduler();
 
   const toolContext = {
+    readFileCache: new Map(),
     hookDb: hermeticExecution ? null : options.hookDb || null,
     skillLoader: options.skillLoader || _defaultSkillLoader,
     skillOutcomeIndex: options.skillOutcomeIndex,
     skillVectorAuthority: options.skillVectorAuthority,
+    skillRetrievalRevocationReader: options.skillRetrievalRevocationReader,
     // 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
@@ -13346,6 +13434,7 @@ export async function* agentLoop(messages, options) {
     // Parent LLM config — forwarded to spawn_sub_agent so a delegated subagent
     // inherits the provider/key and can override just the model (cc agents `model:`).
     llmOptions: {
+      ...(evolutionIngress === null ? {} : { evolutionIngress }),
       provider: options.provider || null,
       model: options.model || null,
       baseUrl: options.baseUrl || null,
@@ -13521,11 +13610,8 @@ export async function* agentLoop(messages, options) {
     }
   }
 
-  // Phase 7 parity harness hook: tests can inject a mock LLM function via
-  // `options.chatFn` to drive the loop deterministically without hitting a
-  // real provider. Production code path is unchanged — the fallback is the
-  // real `chatWithTools`.
-  let llmCall = options.chatFn || chatWithTools;
+  // llmCall was captured before startup awaits. With evolution ingress, only
+  // a factory-owned canonical fallback bound to this Run may replace it.
 
   // Runnable-first auth recovery: if the resolved provider's key is missing /
   // wrong / expired, self-heal to a provider we can actually run (endpoint-
@@ -13621,8 +13707,22 @@ export async function* agentLoop(messages, options) {
   // one-shot guard means a model that keeps returning empty turns completes
   // rather than looping forever (the iteration budget is the hard backstop).
   let emptyThinkingReprompted = false;
+  const readFileLoopGuard = new ReadFileLoopGuard();
 
   while (budget.hasRemaining()) {
+    readFileLoopGuard.finishBatch();
+    if (readFileLoopGuard.stalled) {
+      await _awaitBackgroundUsageSettlement(
+        backgroundSubAgents,
+        backgroundUsageFailureState,
+      );
+      yield* _drainSubAgentUsage(subAgentUsageSink);
+      const error = new Error(
+        "Repeated unchanged file reads: stopped after three tool batches made no new reading progress, including a recovery attempt. The task is not complete. Continue with a different file section or a targeted search.",
+      );
+      error.code = "CC_AGENT_REPEATED_FILE_READ";
+      throw error;
+    }
     if (typeof toolContext.sessionBudget?.consumeTurn === "function") {
       const turnBudgetId = `turn:${createHash("sha256")
         .update(`${runId}:t${budget.consumed + 1}`, "utf8")
@@ -14066,6 +14166,7 @@ export async function* agentLoop(messages, options) {
       } catch (_e) {
         if (isAbortError(_e) || signal?.aborted) throw _e;
         if (_e?.runtimeLedgerPersistence === true) throw _e;
+        if (_e?.code === "CC_AGENT_EVOLUTION_INGRESS_FAILED") throw _e;
         if (
           _e?.workflowEffectOutcomeUnknown === true &&
           _e?.compactionFailureReported === true
@@ -14175,6 +14276,20 @@ export async function* agentLoop(messages, options) {
     // system-message supplement that is NOT persisted to messages history.
     let callMessages = messages;
     const contextMemoryTrustedSystemIndexes = [];
+    if (readFileLoopGuard.progressHint) {
+      callMessages = [
+        ...callMessages,
+        { role: "system", content: readFileLoopGuard.progressHint },
+      ];
+      contextMemoryTrustedSystemIndexes.push(callMessages.length - 1);
+    }
+    if (readFileLoopGuard.recoveryHint) {
+      callMessages = [
+        ...callMessages,
+        { role: "system", content: readFileLoopGuard.recoveryHint },
+      ];
+      contextMemoryTrustedSystemIndexes.push(callMessages.length - 1);
+    }
     if (!hermeticExecution && typeof options.prepareCall === "function") {
       try {
         const hook = await options.prepareCall({
@@ -14188,7 +14303,7 @@ export async function* agentLoop(messages, options) {
           hook.systemSuffix
         ) {
           callMessages = [
-            ...messages,
+            ...callMessages,
             { role: "system", content: hook.systemSuffix },
           ];
           contextMemoryTrustedSystemIndexes.push(callMessages.length - 1);
@@ -14250,9 +14365,13 @@ export async function* agentLoop(messages, options) {
             canonicalProviderContext.selectedToolNames,
         }
       : effectiveToolOptions;
-    const providerCallOptions = providerRequestId
+    const requestOptions = providerRequestId
       ? { ...plannedProviderOptions, providerRequestId }
       : plannedProviderOptions;
+    const providerCallOptions =
+      evolutionIngress !== null
+        ? { ...requestOptions, evolutionIngress }
+        : requestOptions;
     const modelUsageCall = {
       type: "model-usage-started",
       callId: _newModelUsageCallId("model"),
@@ -14575,6 +14694,7 @@ export async function* agentLoop(messages, options) {
 
     // Add assistant message with tool calls
     messages.push(msg);
+    readFileLoopGuard.startBatch(toolCalls.length);
 
     // Concurrent READ-ONLY batch (latency optimization). When every call in the
     // turn is a well-formed read-only built-in (pure fs/DB reads — no mutation,
@@ -14683,6 +14803,7 @@ export async function* agentLoop(messages, options) {
         _throwBackgroundUsageFailureState(backgroundUsageFailureState);
         const { result: toolResult, error: toolError } = await promise;
         throwIfAborted(signal);
+        readFileLoopGuard.record(call.function.name, toolResult);
         const failed = emitToolHookLifecycle({
           tool: call.function.name,
           args: toolArgs,
@@ -14700,8 +14821,10 @@ export async function* agentLoop(messages, options) {
           failed,
         });
         const warningMsg = budget.toWarningMessage();
-        const resultStr = capToolResultString(
-          safeStringifyToolResult(toolResult),
+        const resultStr = toolResultForModel(
+          call.function.name,
+          toolResult,
+          messages,
         );
         const toolContent = warningMsg
           ? `${resultStr}\n\n${warningMsg}`
@@ -15150,9 +15273,8 @@ export async function* agentLoop(messages, options) {
         // Cap an individual tool result so one giant output can't blow the
         // context — but tell the model when we cut it (no more silent
         // mid-content slice). See MAX_TOOL_RESULT_CHARS / capToolResultString.
-        const resultStr = capToolResultString(
-          safeStringifyToolResult(toolResult),
-        );
+        const resultStr = toolResultForModel(toolName, toolResult, messages);
+        readFileLoopGuard.record(toolName, toolResult);
         const toolContent = warningMsg
           ? `${resultStr}\n\n${warningMsg}`
           : resultStr;
@@ -15243,7 +15365,7 @@ export async function* agentLoop(messages, options) {
     backgroundUsageFailureState,
   );
   yield* _drainSubAgentUsage(subAgentUsageSink);
-  yield { type: "iteration-budget-exhausted", budget: budget.toSummary() };
+  yield { type: "iteration-budget-exhausted", budget: budget.limit };
   yield {
     type: "response-complete",
     content: `(Iteration budget exhausted — ${budget.toSummary()})`,

package/src/runtime/agent-runtime.js

@@ -34,8 +34,13 @@ import { registerHostHooksV2Workspace } from "../lib/hooks-v2-workspace-context.
 import { captureStructuredMemoryPolicyReceiptWriter } from "../lib/evolution/structured-memory-policy-receipt-writer.js";
 import { captureStructuredMemoryAgentControlPlane } from "../lib/evolution/structured-memory-agent-control-plane.js";
 import { captureAgentEvolutionIngress } from "../lib/evolution/agent-evolution-ingress.js";
+import {
+  AGENT_EVOLUTION_SESSION_SCHEMA,
+  waitForAgentEvolutionSession,
+} from "../lib/evolution/agent-evolution-session-lifecycle.js";
 import { captureAgentSkillOutcomeIndex } from "../lib/evolution/agent-evolution-runtime-composition-brand.js";
 import { captureSkillVectorAuthority } from "../lib/skill-vector-authority.js";
+import { captureSkillRetrievalRevocationReader } from "../lib/evolution/skill-retrieval-revocation-authority.js";
 
 const {
   DEFAULT_ALLOWED_MCP_SERVER_NAMES,
@@ -79,6 +84,12 @@ export class AgentRuntime {
       deps.skillVectorAuthority == null
         ? null
         : captureSkillVectorAuthority(deps.skillVectorAuthority);
+    this.skillRetrievalRevocationReader =
+      deps.skillRetrievalRevocationReader == null
+        ? null
+        : captureSkillRetrievalRevocationReader(
+            deps.skillRetrievalRevocationReader,
+          );
     if (
       this.evolutionIngress !== null &&
       this.skillOutcomeIndex !== null &&
@@ -99,6 +110,21 @@ export class AgentRuntime {
     ) {
       throw new Error("Agent retrieval authorities must share one tenant");
     }
+    if (
+      this.skillVectorAuthority !== null &&
+      this.skillRetrievalRevocationReader !== null &&
+      this.skillVectorAuthority.tenantId !==
+        this.skillRetrievalRevocationReader.tenantId
+    ) {
+      throw new Error("Agent retrieval authorities must share one tenant");
+    }
+    if (
+      retrievalTenant !== null &&
+      this.skillRetrievalRevocationReader !== null &&
+      retrievalTenant !== this.skillRetrievalRevocationReader.tenantId
+    ) {
+      throw new Error("Agent retrieval authorities must share one tenant");
+    }
     this.structuredMemoryControlPlane =
       deps.structuredMemoryControlPlane == null
         ? null
@@ -333,8 +359,20 @@ export class AgentRuntime {
       ...(this.skillVectorAuthority === null
         ? {}
         : { skillVectorAuthority: this.skillVectorAuthority }),
+      ...(this.skillRetrievalRevocationReader === null
+        ? {}
+        : {
+            skillRetrievalRevocationReader: this.skillRetrievalRevocationReader,
+          }),
     });
     if (this.evolutionIngress !== null) {
+      if (result?.schema === AGENT_EVOLUTION_SESSION_SCHEMA) {
+        return await waitForAgentEvolutionSession(
+          result,
+          this.evolutionIngress,
+        );
+      }
+      if (result?.started === false) return result;
       await this.evolutionIngress.complete();
     }
     return result;
@@ -510,6 +548,11 @@ export class AgentRuntime {
       ...(this.skillVectorAuthority === null
         ? {}
         : { skillVectorAuthority: this.skillVectorAuthority }),
+      ...(this.skillRetrievalRevocationReader === null
+        ? {}
+        : {
+            skillRetrievalRevocationReader: this.skillRetrievalRevocationReader,
+          }),
     });
 
     server.on("connection", ({ clientId, ip }) => {

package/src/runtime/coding-agent-contract-shared.cjs

@@ -28,7 +28,7 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
     kind: "filesystem",
     tier: "mvp",
     description:
-      "Read a file's content. For a large file, page through it with offset+limit (line range) instead of re-reading the head. Jupyter notebooks (.ipynb) are rendered as a compact cell listing (index/id/type/source, outputs hidden) for use with notebook_edit — pass raw:true for the underlying JSON.",
+      "Read a file's content. Use search_files to locate relevant sections and offset+limit to read them. For large files, follow the returned nextRead cursor; range describes only the lines actually returned. Reuse unchanged content already in context instead of re-reading the same page. Jupyter notebooks (.ipynb) are rendered as a compact cell listing for notebook_edit — pass raw:true for underlying JSON.",
     inputSchema: {
       type: "object",
       properties: {
@@ -43,6 +43,12 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
           description:
             "Maximum number of lines to return starting at offset (omit to read to end, subject to the size cap).",
         },
+        column: {
+          type: "integer",
+          minimum: 1,
+          description:
+            "1-based character position within the first rendered line. Use the column from nextRead to continue an oversized single line without repeating its beginning.",
+        },
         hashed: {
           type: "boolean",
           description: