chainlesschain 0.166.104 → 0.166.106

package/src/data/changelog.json

@@ -1,6 +1,32 @@
 {
   "source": "CHANGELOG.md",
   "releases": [
+    {
+      "productVersion": null,
+      "cliVersion": "0.166.106",
+      "cliVersions": ["0.166.105", "0.166.106"],
+      "date": "2026-10-18",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Fixed - cc CLI 0.166.106: task delivery follow-up (candidate, 2026-10-18)",
+          "body": "- Guide coding tasks toward brief action statements and complete file writes split into bounded segments.\n- Ground regression expectations and defaults in the source contract, exercise actual boundaries with valid fault-injection fixtures, and use independent expected values or authoritative state.\n- Preserve the explicit provider reason for HTTP 403 responses that are not authentication or billing errors.\n- Keep JetBrains asynchronous draft-save receipts in a separate status update so they do not interrupt the assistant reply.\n- Wait up to two seconds for final JetBrains stdout callbacks on the background process waiter and schedule exit alongside result rendering on the IDE event queue.\n- Close unused Windows ACL subprocess input, require complete output before success, and share one bounded drain/cleanup deadline; native ACL startup timeouts remain under investigation.\n- Pair candidate VS Code 0.37.151 and JetBrains 0.4.168 with CLI 0.166.106; retain the existing published child-package versions.\n- Current public versions remain CLI 0.166.105, Open VSX 0.37.150 and JetBrains 0.4.167. Publish this candidate only after complete exact-commit gates, npm OIDC and public artifact readback, then retest unfinished samples.\n- Public .105 retesting completed generation 20/20 and acceptance 20/20, adding 6 candidate acceptances and 6 full-flow passes. Cumulative acceptance is 31/45 (ordinary 26/36, first-use 5/9), with 14 remaining. The original 25 accepted artifacts were reused byte-for-byte; cross-version cumulative acceptance is not a single-round 45/45 success. Candidates .106/.151/.168 remain unpublished and have not been retested."
+        }
+      ]
+    },
+    {
+      "productVersion": null,
+      "cliVersion": "0.166.105",
+      "cliVersions": ["0.166.105"],
+      "date": "2026-10-18",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Fixed - cc CLI 0.166.105: task delivery quality and safe diagnostics (candidate, 2026-10-18)",
+          "body": "- Add general coding guidance and static relative-import feedback without executing candidate code or injecting task-specific answers.\n- Do not report completion while deferred writes remain; distinguish provider transport aborts from owned cancellation.\n- Preserve bounded allowlisted transport cause details without changing original errors, exits, fetch, retries or replay.\n- Pair candidate VS Code 0.37.150 and JetBrains 0.4.167 with CLI 0.166.105 after exact-commit matrices, OIDC publishing and public readback. JetBrains restores saved Markdown consistently with live rendering.\n- Campaign: 25/45 cumulative candidate acceptances; latest 22/25 collected, 4 end-to-end passes, 3 Windows JetBrains samples ongoing. New versions are not yet published or retested."
+        }
+      ]
+    },
     {
       "productVersion": null,
       "cliVersion": "0.166.104",

package/src/lib/coding-task-guidance.js

@@ -0,0 +1,15 @@
+/** Shared correctness guidance for normal and file-only coding sessions. */
+export const CODING_TASK_QUALITY_GUIDANCE = `Coding task quality:
+- Read the actual implementation and its exported API before writing a caller or test. Check parameter order, return shapes, asynchronous lifecycle and fixture requirements against the source; an example in another directory can have different relative imports.
+- Keep progress explanations to one or two sentences. Once the relevant API and behavior are clear, make the next tool call; resolve a remaining uncertainty with a targeted read. Put implementation code directly in write/edit tool arguments instead of rehearsing the code or repeatedly analyzing the same source in ordinary assistant text.
+- Resolve each relative import from the destination file's directory. Read back the completed file and fix newDiagnostics from write/edit results before finishing. A successful write confirms persistence, not syntax, test execution or acceptance.
+- Regression tests need a working positive control and a negative control that exercises the requested behavior through the real production entry point. Assert observable effects; avoid mocks or alternate calls that bypass the behavior under test. Complete the current worker/request when testing cancellation and replacement.
+- For boundary regressions, derive expected defaults, computed values and rejection rules from the implementation or the explicit requested contract. Inject mismatched, tampered or stale input through the real entry point while keeping other prerequisites valid; verify that the fixture reaches the intended check rather than failing during setup. Compare observable results with independent expected values or authoritative state, not a helper that merely recomputes the same result.
+- Use available execution tools for a focused check when permitted. When execution tools are unavailable, inspect imports, API contracts and fixtures using the available file tools, and clearly say that tests were not run. Never describe a read-back or static check as a passing test or end-to-end verification.
+- Finish requested file changes before the final response. Reserve output and remaining requests for writing, read-back and focused validation. For large files, aim for a few thousand characters of new content per call: write a small complete section, then extend it with edit_file using a unique existing anchor and a replacement containing that anchor plus the next complete section. Keep each tool call complete and wait for its result before extending the file again; do not repeatedly rewrite the growing file. State what was delivered, what was checked and what remains unverified.`;
+
+export const HERMETIC_CODING_SYSTEM_PROMPT = `You are a hermetic coding assistant. The exposed file tools are the complete tool surface. Inspect and mutate only the exact paths authorized by the user request. Do not invoke hidden tools, commands, language servers or other execution paths.
+
+${CODING_TASK_QUALITY_GUIDANCE}
+
+Return a concise, evidence-based completion message within these tool limits.`;

package/src/lib/file-import-diagnostics.js

@@ -0,0 +1,246 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "acorn";
+
+export const FILE_IMPORT_LIMITS = Object.freeze({
+  contentBytes: 256 * 1024,
+  references: 64,
+  specifierChars: 512,
+});
+
+const JS_EXTENSION = /\.(?:js|mjs|cjs)$/;
+
+function inside(root, target) {
+  const relative = path.relative(root, target);
+  return (
+    relative === "" ||
+    (!path.isAbsolute(relative) &&
+      relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`))
+  );
+}
+
+// Inspect each component before descending. Never stat/realpath a link, read
+// target contents, enumerate directories, or include OS errors in feedback.
+// As with other path-based Node APIs, this is not atomic against directory
+// replacement by another process. The caller supplies its authorized root.
+function inspectPath(root, target) {
+  if (!inside(root, target)) return "outside-workspace";
+  const components = path
+    .relative(root, target)
+    .split(path.sep)
+    .filter(Boolean);
+  let current = root;
+  for (let index = -1; index < components.length; index++) {
+    if (index >= 0) current = path.join(current, components[index]);
+    let stat;
+    try {
+      stat = fs.lstatSync(current);
+    } catch (error) {
+      return error?.code === "ENOENT" ? "missing" : "unavailable";
+    }
+    if (stat.isSymbolicLink()) return "symbolic-link";
+    if (index < components.length - 1 && !stat.isDirectory()) {
+      return "missing";
+    }
+    if (index === components.length - 1) {
+      return stat.isFile() ? "file" : "not-file";
+    }
+  }
+  return "not-file";
+}
+
+function inspectReference(root, target, kind) {
+  const state = inspectPath(root, target);
+  if (kind !== "require") return state;
+  // CommonJS can load directories and append extensions even when a request
+  // already has a suffix. Do not claim those uncertain cases are unresolved.
+  if (state === "not-file") return "commonjs-resolution";
+  if (state === "missing") {
+    for (const extension of [".js", ".json", ".node"]) {
+      const fallback = inspectPath(root, target + extension);
+      if (fallback !== "missing" && fallback !== "not-file") {
+        return "commonjs-resolution";
+      }
+    }
+  }
+  return state;
+}
+
+function parseSource(content, extension) {
+  const options = { ecmaVersion: "latest", locations: true };
+  if (extension === ".cjs") {
+    return parse(content, {
+      ...options,
+      sourceType: "script",
+      allowReturnOutsideFunction: true,
+    });
+  }
+  try {
+    return parse(content, { ...options, sourceType: "module" });
+  } catch (error) {
+    if (extension === ".mjs") throw error;
+    return parse(content, {
+      ...options,
+      sourceType: "script",
+      allowReturnOutsideFunction: true,
+    });
+  }
+}
+
+function collectReferences(ast) {
+  const references = [];
+  const pending = [{ node: ast, parent: null }];
+  let uncertainRequire = false;
+  let truncated = false;
+  while (pending.length) {
+    const { node, parent } = pending.pop();
+    // Conservative across the whole file: local bindings, assignments, and
+    // indirect uses make require's meaning uncertain. Imports remain useful.
+    if (
+      (node.type === "Identifier" &&
+        node.name === "require" &&
+        !(parent?.type === "CallExpression" && parent.callee === node)) ||
+      node.type === "WithStatement" ||
+      (node.type === "CallExpression" && node.callee?.name === "eval")
+    ) {
+      uncertainRequire = true;
+    }
+    let source;
+    let kind;
+    if (
+      node.type === "ImportDeclaration" ||
+      node.type === "ExportNamedDeclaration" ||
+      node.type === "ExportAllDeclaration" ||
+      node.type === "ImportExpression"
+    ) {
+      source = node.source;
+      kind = "import";
+    } else if (
+      node.type === "CallExpression" &&
+      !node.optional &&
+      node.callee?.type === "Identifier" &&
+      node.callee.name === "require" &&
+      node.arguments.length === 1
+    ) {
+      source = node.arguments[0];
+      kind = "require";
+    }
+    if (
+      source?.type === "Literal" &&
+      typeof source.value === "string" &&
+      /^\.{1,2}\//.test(source.value) &&
+      JS_EXTENSION.test(source.value) &&
+      !/[\\%?#:\u0000-\u001f\u007f]/.test(source.value)
+    ) {
+      if (references.length < FILE_IMPORT_LIMITS.references) {
+        references.push({ source, kind });
+      } else {
+        truncated = true;
+      }
+    }
+    const children = [];
+    for (const value of Object.values(node)) {
+      if (value?.type) children.push(value);
+      else if (Array.isArray(value)) {
+        for (const child of value) if (child?.type) children.push(child);
+      }
+    }
+    for (let index = children.length - 1; index >= 0; index--) {
+      pending.push({ node: children[index], parent: node });
+    }
+  }
+  return { references, uncertainRequire, truncated };
+}
+
+/**
+ * Best-effort feedback after an authorized write. Only explicit JS relative
+ * runtime references are checked, using supplied content and metadata inside
+ * workspaceRoot. This does not run code, resolve packages, or prove tests pass.
+ * Missing/inaccessible inputs and unsupported syntax never throw to the writer.
+ * line/column are one-based. uncheckedReferences never disclose resolved paths.
+ */
+export function collectFileImportDiagnostics(input) {
+  const result = {
+    status: "skipped",
+    diagnostics: [],
+    checkedReferences: 0,
+    uncheckedReferences: [],
+    truncated: false,
+  };
+  const skip = (reason) => ({ ...result, reason });
+  try {
+    const { filePath, content, workspaceRoot } = input ?? {};
+    if (
+      typeof filePath !== "string" ||
+      !filePath ||
+      filePath.length > 4096 ||
+      typeof workspaceRoot !== "string" ||
+      !workspaceRoot ||
+      workspaceRoot.length > 4096 ||
+      !path.isAbsolute(workspaceRoot) ||
+      typeof content !== "string"
+    ) {
+      return skip("invalid-input");
+    }
+    if (!JS_EXTENSION.test(filePath)) return skip("unsupported-file");
+    if (
+      content.length > FILE_IMPORT_LIMITS.contentBytes ||
+      Buffer.byteLength(content, "utf8") > FILE_IMPORT_LIMITS.contentBytes
+    ) {
+      return skip("content-limit");
+    }
+    const root = path.resolve(workspaceRoot);
+    const file = path.resolve(root, filePath);
+    if (!inside(root, file)) return skip("outside-workspace");
+    const fileState = inspectPath(root, file);
+    if (fileState !== "file") return skip(fileState);
+    let ast;
+    try {
+      ast = parseSource(content, path.extname(file));
+    } catch {
+      return skip("unsupported-syntax");
+    }
+    const { references, uncertainRequire, truncated } = collectReferences(ast);
+    result.status = "checked";
+    result.truncated = truncated;
+    for (const { source, kind } of references) {
+      const location = {
+        specifier: source.value.slice(0, FILE_IMPORT_LIMITS.specifierChars),
+        line: source.loc.start.line,
+        column: source.loc.start.column + 1,
+      };
+      let state;
+      if (source.value.length > FILE_IMPORT_LIMITS.specifierChars) {
+        state = "specifier-limit";
+      } else if (kind === "require" && uncertainRequire) {
+        state = "uncertain-require";
+      } else {
+        state = inspectReference(
+          root,
+          path.resolve(path.dirname(file), source.value),
+          kind,
+        );
+      }
+      if (state === "file" || state === "missing" || state === "not-file") {
+        result.checkedReferences++;
+        if (state !== "file") {
+          result.diagnostics.push({
+            source: "relative-import",
+            code: "UNRESOLVED_RELATIVE_IMPORT",
+            severity: "error",
+            filePath: file,
+            ...location,
+            message: `Relative import ${JSON.stringify(location.specifier)} does not point to an existing file from this file's directory. Verify the importing file's location before running tests.`,
+          });
+        }
+      } else {
+        result.uncheckedReferences.push({ ...location, reason: state });
+      }
+    }
+    return result;
+  } catch {
+    // Do not allow optional feedback to turn a completed mutation into failure.
+    return skip("unavailable");
+  }
+}

package/src/lib/provider-http-error.js

@@ -84,11 +84,10 @@ export function formatProviderHttpError(
     );
   }
   if (status === 403) {
-    return (
-      `${base} — access forbidden` +
-      (detailSentence ? `: ${detailSentence}` : "") +
-      ". Check the API key, model access permissions, and account status/balance."
-    );
+    // Gateways can use 403 for request/output policy failures. An explicit
+    // reason without auth/billing evidence must not imply a credential fix.
+    if (detailSentence) return `${base} — ${detailSentence}.`;
+    return `${base} — access forbidden. Check the API key, model access permissions, and account status/balance.`;
   }
   if (status === 429) return `${base} — rate limited; please retry shortly.`;
   return detailSentence ? `${base} — ${detailSentence}` : base;

package/src/lib/transport-error-details.js

@@ -0,0 +1,83 @@
+import { types } from "node:util";
+
+const NAMES = new Set([
+  "Error",
+  "TypeError",
+  "AggregateError",
+  "AbortError",
+  "TimeoutError",
+  "ConnectTimeoutError",
+  "HeadersTimeoutError",
+  "BodyTimeoutError",
+  "SocketError",
+  "RequestAbortedError",
+  "ClientDestroyedError",
+  "ClientClosedError",
+]);
+const CODES = new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ETIMEDOUT",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "EPIPE",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "CERT_HAS_EXPIRED",
+  "ABORT_ERR",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_ABORTED",
+  "UND_ERR_DESTROYED",
+  "UND_ERR_CLOSED",
+  "UND_ERR_REQ_CONTENT_LENGTH_MISMATCH",
+  "UND_ERR_RES_CONTENT_LENGTH_MISMATCH",
+]);
+
+// Never invoke accessors, coercion hooks or Proxy traps. Native Error.name is
+// inherited, so inspect a bounded number of prototype data descriptors.
+function data(object, key) {
+  for (let depth = 0; depth < 4 && object !== null; depth++) {
+    if (typeof object !== "object" || types.isProxy(object)) return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (descriptor) return "value" in descriptor ? descriptor.value : undefined;
+    object = Object.getPrototypeOf(object);
+  }
+  return undefined;
+}
+
+/** Optional diagnostic projection only: no messages, endpoints or request data. */
+export function transportErrorDetails(error) {
+  try {
+    const name = data(error, "name");
+    const code = data(error, "code");
+    let causeCode;
+    const seen = new Set([error]);
+    let cause = error;
+    for (let depth = 0; depth < 4; depth++) {
+      cause = data(cause, "cause");
+      if (!cause || seen.has(cause)) break;
+      seen.add(cause);
+      const value = data(cause, "code");
+      if (CODES.has(value)) {
+        causeCode = value;
+        break;
+      }
+    }
+    if (!CODES.has(code) && !causeCode) return undefined;
+    return {
+      kind: "transport",
+      ...(NAMES.has(name) ? { name } : {}),
+      ...(CODES.has(code) ? { code } : {}),
+      ...(causeCode ? { causeCode } : {}),
+    };
+  } catch {
+    // Diagnostics must never replace the original error or exit outcome.
+    return undefined;
+  }
+}

package/src/runtime/agent-core.js

@@ -49,6 +49,7 @@ import { ReadFileLoopGuard } from "../lib/read-file-loop-guard.js";
 import { gitToolInputError } from "../lib/git-tool-input.js";
 import { shellOutputPage, shellOutputPreview } from "../lib/shell-output.js";
 import { DIAGNOSTIC_WORKFLOW_GUIDANCE } from "../lib/diagnostic-workflow.js";
+import { CODING_TASK_QUALITY_GUIDANCE } from "../lib/coding-task-guidance.js";
 import { RemoteReadLoopGuard } from "../lib/remote-read-loop-guard.js";
 import {
   isPrActionRequest,
@@ -1167,6 +1168,8 @@ export function getBaseSystemPrompt(cwd) {
 You have access to tools that let you read files, write files, edit files, run shell commands, and search the codebase. When the user asks you to do something, USE THE TOOLS to actually do it — don't just describe what should be done.
 
 Key behaviors:
+${CODING_TASK_QUALITY_GUIDANCE}
+
 - A new user message may arrive before the previous task finishes. Incorporate corrections and added requests while preserving unfinished authorized work, unless the user cancels or replaces it. Use the completed tool results already in history; do not restart the investigation.
 - When asked to modify code, read the file first, then edit it
 - When asked to create something, use write_file to create it
@@ -4927,19 +4930,63 @@ export async function _withPostEditDiagnostics(
   cwd,
   additionalDirectories,
   managedCheckpoint = false,
+  writtenContent = null,
 ) {
+  // Parsing the bytes we just wrote is safe even when starting a language
+  // server is forbidden. Feed definite local import mistakes back in the same
+  // tool result; a successful write still means persistence, not test success.
+  let enriched = result;
+  if (
+    result?.success === true &&
+    typeof writtenContent === "string" &&
+    /\.(?:js|mjs|cjs)$/i.test(filePath) &&
+    process.env.CC_EDIT_DIAGNOSTICS !== "0"
+  ) {
+    try {
+      const root = pickRootForFile(
+        path.resolve(cwd || process.cwd(), filePath),
+        workspaceRootsFor(cwd, additionalDirectories),
+      );
+      if (root) {
+        const { collectFileImportDiagnostics } = await import(
+          "../lib/file-import-diagnostics.js"
+        );
+        const checked = collectFileImportDiagnostics({
+          filePath,
+          content: writtenContent,
+          workspaceRoot: root,
+        });
+        if (checked.diagnostics.length) {
+          enriched = {
+            ...result,
+            newDiagnostics: [
+              ...(result.newDiagnostics || []),
+              ...checked.diagnostics.slice(0, 8),
+            ],
+          };
+        }
+      }
+    } catch {
+      // Optional diagnostics must not turn a persisted edit into a failed one.
+    }
+  }
   // A cold language server is a long-lived child process. Starting one inside
   // a managed workspace transaction would keep a writer bound past tool
   // settlement and make commit/rollback unverifiable. Managed edits therefore
   // skip this best-effort enrichment; callers can request diagnostics after the
   // checkpoint has sealed.
-  if (managedCheckpoint) return result;
+  if (managedCheckpoint) return enriched;
   const newDiagnostics = await _postEditDiagnostics(
     filePath,
     cwd,
     additionalDirectories,
   );
-  return newDiagnostics ? { ...result, newDiagnostics } : result;
+  return newDiagnostics
+    ? {
+        ...enriched,
+        newDiagnostics: [...(enriched.newDiagnostics || []), ...newDiagnostics],
+      }
+    : enriched;
 }
 
 // ─── Lazy subtree instruction injection (large-monorepo lever) ─────────────
@@ -5791,6 +5838,7 @@ async function executeToolInner(
             cwd,
             additionalDirectories,
             managedCheckpoint || hermeticExecution,
+            args.content,
           ),
           filePath,
           cwd,
@@ -5992,6 +6040,7 @@ async function executeToolInner(
             cwd,
             additionalDirectories,
             managedCheckpoint || hermeticExecution,
+            newContent,
           ),
           filePath,
           cwd,
@@ -6094,6 +6143,7 @@ async function executeToolInner(
             cwd,
             additionalDirectories,
             managedCheckpoint || hermeticExecution,
+            result.content,
           ),
           filePath,
           cwd,
@@ -14622,6 +14672,53 @@ export async function* agentLoop(messages, options) {
     options.hostResourceBudget || new HostResourceBudget();
   const taskProgressTracker =
     options.taskProgressTracker || new TaskProgressTracker();
+  // A subtree preflight is deliberately not an executed mutation. Keep this
+  // obligation outside transcript compaction and never replay it automatically.
+  const pendingSubtreeMutations = new Map();
+  let subtreeMutationReprompted = false;
+  const recordSubtreeMutation = (tool, args, result) => {
+    if (!GUARDED_FILE_MUTATION_TOOLS.has(tool)) return;
+    if (!args || typeof args !== "object" || Array.isArray(args)) return;
+    // Invalid tool arguments/results must retain their existing error path;
+    // bookkeeping must not introduce a new exception or completion verdict.
+    const requestedPaths = fileMutationPaths(tool, args);
+    if (
+      !requestedPaths.length ||
+      requestedPaths.some((target) => typeof target !== "string")
+    )
+      return;
+    const targets = [
+      ...new Set(
+        requestedPaths.map((target) =>
+          path.resolve(options.cwd || process.cwd(), target),
+        ),
+      ),
+    ].sort();
+    // These tools are alternative ways to deliver content to the same target.
+    // A successful explicit replacement must settle a deferred edit (and vice
+    // versa); move/delete/notebook effects retain their distinct obligations.
+    const effect = ["write_file", "edit_file", "edit_file_hashed"].includes(tool)
+      ? "file-content"
+      : tool;
+    const key = JSON.stringify([effect, targets]);
+    if (
+      result?.policy?.via === "subtree-instructions" &&
+      result.policy.decision === "deferred" &&
+      result.mutationPerformed === false
+    ) {
+      pendingSubtreeMutations.set(key, { tool, targets });
+    } else if (
+      result &&
+      !result.error &&
+      result.success === true &&
+      result.isError !== true &&
+      result.policy?.decision !== "deny" &&
+      result.policy?.decision !== "deferred" &&
+      result.mutationPerformed !== false
+    ) {
+      pendingSubtreeMutations.delete(key);
+    }
+  };
   const signal = options.signal || null;
   const workflowEffectId = _normalizeWorkflowEffectId(options.workflowEffectId);
   // Optional OpenTelemetry recorder (TelemetryRecorder). When present, the loop
@@ -16397,6 +16494,42 @@ export async function* agentLoop(messages, options) {
         }
         continue;
       }
+      if (pendingSubtreeMutations.size) {
+        const pending = [...pendingSubtreeMutations.values()];
+        if (!subtreeMutationReprompted && budget.remaining() > 0) {
+          subtreeMutationReprompted = true;
+          messages.push({ role: "assistant", content: msg.content || "" });
+          messages.push({
+            role: "user",
+            content:
+              "Runtime status: these mutations were deferred before any effect: " +
+              JSON.stringify(pending) +
+              ". Review the authoritative subtree instructions already returned. " +
+              "If still authorized and appropriate, explicitly issue the required tool call. " +
+              "Do not bypass rules or perform a prohibited write. Otherwise report the unfinished work and its blocker. " +
+              "A promise to retry does not execute the mutation.",
+          });
+          yield {
+            type: "iteration-warning",
+            message:
+              "Subtree-deferred mutations remain unexecuted; one recovery turn requested.",
+          };
+          continue;
+        }
+        yield {
+          type: "response-complete",
+          content:
+            (msg.content ? msg.content + "\n\n" : "") +
+            "Incomplete: subtree-deferred mutations remain unexecuted.",
+        };
+        yield {
+          type: "run-ended",
+          runId,
+          reason: "deferred-mutation-unresolved",
+          pendingMutations: pending,
+        };
+        return;
+      }
       // Surface the final answer's extended-thinking reasoning (Anthropic, when
       // --think is on) so non-streaming consumers (the REPL) can show it. The
       // streaming path forwards reasoning live via onThinking instead.
@@ -16638,6 +16771,7 @@ export async function* agentLoop(messages, options) {
         } = await promise;
         if (fatalError) throw fatalError;
         throwIfAborted(signal);
+        recordSubtreeMutation(call.function.name, toolArgs, toolResult);
         const taskAdvanced = taskProgressTracker.record(
           call.function.name,
           toolResult,
@@ -17181,6 +17315,7 @@ export async function* agentLoop(messages, options) {
         // context — but tell the model when we cut it (no more silent
         // mid-content slice). See MAX_TOOL_RESULT_CHARS / capToolResultString.
         const resultStr = toolResultForModel(toolName, toolResult, messages);
+        recordSubtreeMutation(toolName, toolArgs, toolResult);
         const taskAdvanced = taskProgressTracker.record(
           toolName,
           toolResult,

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

@@ -77,7 +77,8 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
     title: "Write File",
     kind: "filesystem",
     tier: "mvp",
-    description: "Write content to a file (create or overwrite)",
+    description:
+      "Write content to a file (create or overwrite). For a large new file, write a small complete section first, then extend it with edit_file using a unique existing anchor. Aim for a few thousand characters of new content per call and wait for the result before continuing; each write_file call replaces the whole file.",
     inputSchema: {
       type: "object",
       properties: {
@@ -200,7 +201,7 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
     kind: "filesystem",
     tier: "mvp",
     description:
-      "Replace a string in a file. old_string must match EXACTLY ONE place — include enough surrounding context to make it unique, or the edit is rejected. Pass replace_all:true to change every occurrence instead.",
+      "Replace a string in a file. old_string must match EXACTLY ONE place — include enough surrounding context to make it unique, or the edit is rejected. To extend a file in small complete sections, use a unique existing anchor as old_string and retain that anchor plus the new section in new_string; do not resend the whole growing file. Wait for each edit result before continuing. Pass replace_all:true to change every occurrence instead.",
     inputSchema: {
       type: "object",
       properties: {