From 6f3ec85d1e74fbe98f05614015b2ef5be0b59f63 Mon Sep 17 00:00:00 2001
From: Aiden Cline <aidenpcline@gmail.com>
Date: Wed, 29 Jul 2026 11:46:26 -0500
Subject: [PATCH] fix(core): clarify Code Mode tool boundary

---
 packages/core/src/codemode/instructions.ts       | 4 +++-
 packages/core/src/codemode/tool.ts               | 2 +-
 packages/core/test/codemode/instructions.test.ts | 3 +++
 packages/core/test/tool-execute.test.ts          | 2 +-
 4 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/core/src/codemode/instructions.ts b/packages/core/src/codemode/instructions.ts
index 7e5d135edb..277590ee8d 100644
--- a/packages/core/src/codemode/instructions.ts
+++ b/packages/core/src/codemode/instructions.ts
@@ -6,7 +6,9 @@ import { Instructions } from "../instructions/index"
 import { CodeModeCatalog } from "./catalog"
 
 // prettier-ignore
-const prompt = (hasMoreTools: boolean) => `The Code Mode tool catalog below is ${hasMoreTools ? "partial" : "complete"}.${hasMoreTools ? `
+const prompt = (hasMoreTools: boolean) => `The Code Mode tool catalog below is ${hasMoreTools ? "partial" : "complete"}.
+
+The Code Mode catalog and \`search\` results are the complete set of tools available within Code Mode. Tools presented elsewhere are not available in this runtime.${hasMoreTools ? `
 
 ## Search
 
diff --git a/packages/core/src/codemode/tool.ts b/packages/core/src/codemode/tool.ts
index 7d9c5106be..b0e6d7b319 100644
--- a/packages/core/src/codemode/tool.ts
+++ b/packages/core/src/codemode/tool.ts
@@ -33,7 +33,7 @@ type CollectedFiles = {
 
 // Invariant model-facing guidance; the changing tool catalog is delivered through Instructions.
 const description = [
-  "Run JavaScript to orchestrate tool calls and compose their results through `{ code }` in a confined Code Mode runtime.",
+  "Run JavaScript in a confined Code Mode runtime to orchestrate tool calls and compose their results.",
   "Imports, direct filesystem access, and timers are unavailable. Do not use `fetch`; all external access goes through `tools`.",
   "Within `{ code }`, the only callable tools are those explicitly listed in the Code Mode catalog instructions or returned by `search`. Inside `{ code }`, ignore tools shown outside the Code Mode catalog. They are not available in the Code Mode runtime.",
   'Call tools through `tools` using only exact paths and signatures from the catalog. Do not infer or normalize tool names; preserve bracket notation such as `tools.<namespace>["tool-name"](input)`.',
diff --git a/packages/core/test/codemode/instructions.test.ts b/packages/core/test/codemode/instructions.test.ts
index 543938c268..17cc00f934 100644
--- a/packages/core/test/codemode/instructions.test.ts
+++ b/packages/core/test/codemode/instructions.test.ts
@@ -44,6 +44,9 @@ describe("CodeModeInstructions", () => {
   it.effect("renders the initial catalog, semantic deltas, and removal", () =>
     Effect.gen(function* () {
       const initialized = yield* readInitial(CodeModeInstructions.make([echo]))
+      expect(initialized.text).toContain(
+        "The Code Mode catalog and `search` results are the complete set of tools available within Code Mode. Tools presented elsewhere are not available in this runtime.",
+      )
       expect(initialized.text).toContain("## Available tools")
       expect(initialized.text).not.toContain("## Search")
       expect(initialized.text).toContain(`  - ${echo.signature} // Echo text`)
diff --git a/packages/core/test/tool-execute.test.ts b/packages/core/test/tool-execute.test.ts
index d679f317fe..fcfcb7aea4 100644
--- a/packages/core/test/tool-execute.test.ts
+++ b/packages/core/test/tool-execute.test.ts
@@ -22,7 +22,7 @@ const createCodeMode = (tools: ReadonlyMap<string, Info>) =>
 test("execute describes invariant Code Mode behavior", () => {
   expect(createCodeMode(new Map()).description).toBe(
     [
-      "Run JavaScript to orchestrate tool calls and compose their results through `{ code }` in a confined Code Mode runtime.",
+      "Run JavaScript in a confined Code Mode runtime to orchestrate tool calls and compose their results.",
       "Imports, direct filesystem access, and timers are unavailable. Do not use `fetch`; all external access goes through `tools`.",
       "Within `{ code }`, the only callable tools are those explicitly listed in the Code Mode catalog instructions or returned by `search`. Inside `{ code }`, ignore tools shown outside the Code Mode catalog. They are not available in the Code Mode runtime.",
       'Call tools through `tools` using only exact paths and signatures from the catalog. Do not infer or normalize tool names; preserve bracket notation such as `tools.<namespace>["tool-name"](input)`.',