oh-my-opencode 4.14.0 → 4.14.1

package/packages/lsp-daemon/dist/ensure-daemon.d.ts

@@ -18,4 +18,5 @@ export interface EnsureDaemonOptions {
 export declare function ensureDaemonRunning(paths: DaemonPaths, deps?: EnsureDaemonDeps, options?: EnsureDaemonOptions): Promise<void>;
 export declare function probeSocket(socketPath: string, timeoutMs?: number): Promise<boolean>;
 export declare function spawnDaemonProcess(paths: DaemonPaths): void;
+export declare function resolveDaemonCliPath(env?: NodeJS.ProcessEnv): string;
 export declare function defaultEnsureDaemonDeps(): EnsureDaemonDeps;

package/packages/lsp-daemon/dist/ensure-daemon.js

@@ -8,6 +8,7 @@ import { tryAcquireLock, unlinkQuietly } from "./lock.js";
 const PROBE_TIMEOUT_MS = 500;
 const DEFAULT_READY_TIMEOUT_MS = 5_000;
 const DEFAULT_POLL_INTERVAL_MS = 100;
+const CODEX_LSP_DAEMON_CLI_ENV = "CODEX_LSP_DAEMON_CLI";
 export class DaemonUnreachableError extends Error {
     constructor(socketPath) {
         super(`LSP daemon did not become reachable at ${socketPath}`);
@@ -68,7 +69,7 @@ export function spawnDaemonProcess(paths) {
     mkdirSync(dirname(paths.log), { recursive: true });
     const logFd = openSync(paths.log, "a");
     try {
-        const cliPath = fileURLToPath(new URL("./cli.js", import.meta.url));
+        const cliPath = resolveDaemonCliPath();
         const child = spawn(execPath, [cliPath, "daemon"], {
             detached: true,
             stdio: ["ignore", logFd, logFd],
@@ -79,6 +80,12 @@ export function spawnDaemonProcess(paths) {
         closeSync(logFd);
     }
 }
+export function resolveDaemonCliPath(env = process.env) {
+    const override = env[CODEX_LSP_DAEMON_CLI_ENV]?.trim();
+    if (override)
+        return override;
+    return fileURLToPath(new URL("./cli.js", import.meta.url));
+}
 export function defaultEnsureDaemonDeps() {
     return {
         probe: (socketPath) => probeSocket(socketPath),
@@ -89,8 +96,7 @@ export function defaultEnsureDaemonDeps() {
         },
         spawnDaemon: (paths) => spawnDaemonProcess(paths),
         sleep: (ms) => new Promise((resolve) => {
-            const timer = setTimeout(resolve, ms);
-            timer.unref?.();
+            setTimeout(resolve, ms);
         }),
         now: () => Date.now(),
     };

package/packages/lsp-daemon/dist/index.js

@@ -1485,6 +1485,7 @@ function unlinkQuietly(path) {
 var PROBE_TIMEOUT_MS = 500;
 var DEFAULT_READY_TIMEOUT_MS = 5000;
 var DEFAULT_POLL_INTERVAL_MS = 100;
+var CODEX_LSP_DAEMON_CLI_ENV = "CODEX_LSP_DAEMON_CLI";
 
 class DaemonUnreachableError extends Error {
   constructor(socketPath) {
@@ -1545,7 +1546,7 @@ function spawnDaemonProcess(paths) {
   mkdirSync2(dirname2(paths.log), { recursive: true });
   const logFd = openSync2(paths.log, "a");
   try {
-    const cliPath = fileURLToPath(new URL("./cli.js", import.meta.url));
+    const cliPath = resolveDaemonCliPath();
     const child = spawn2(execPath, [cliPath, "daemon"], {
       detached: true,
       stdio: ["ignore", logFd, logFd]
@@ -1555,6 +1556,12 @@ function spawnDaemonProcess(paths) {
     closeSync2(logFd);
   }
 }
+function resolveDaemonCliPath(env = process.env) {
+  const override = env[CODEX_LSP_DAEMON_CLI_ENV]?.trim();
+  if (override)
+    return override;
+  return fileURLToPath(new URL("./cli.js", import.meta.url));
+}
 function defaultEnsureDaemonDeps() {
   return {
     probe: (socketPath) => probeSocket(socketPath),
@@ -1565,8 +1572,7 @@ function defaultEnsureDaemonDeps() {
     },
     spawnDaemon: (paths) => spawnDaemonProcess(paths),
     sleep: (ms) => new Promise((resolve2) => {
-      const timer = setTimeout(resolve2, ms);
-      timer.unref?.();
+      setTimeout(resolve2, ms);
     }),
     now: () => Date.now()
   };
@@ -1579,6 +1585,7 @@ import { homedir, tmpdir } from "node:os";
 import { join as join2 } from "node:path";
 var requireFromHere = createRequire(import.meta.url);
 var MAX_SOCKET_PATH_LENGTH = 100;
+var CODEX_LSP_DAEMON_VERSION_ENV = "CODEX_LSP_DAEMON_VERSION";
 function resolveDaemonVersion(requireFn = requireFromHere) {
   for (const candidate of ["./package.json", "../package.json"]) {
     try {
@@ -1600,7 +1607,7 @@ function daemonBaseDir(env = process.env) {
   const home = codexHome && codexHome.length > 0 ? codexHome : join2(homedir(), ".codex");
   return join2(home, "codex-lsp", "daemon");
 }
-function daemonPaths(env = process.env, version = resolveDaemonVersion()) {
+function daemonPaths(env = process.env, version = resolveDaemonVersionFromEnv(env) ?? resolveDaemonVersion()) {
   const dir = join2(daemonBaseDir(env), `v${version}`);
   return {
     version,
@@ -1611,6 +1618,10 @@ function daemonPaths(env = process.env, version = resolveDaemonVersion()) {
     log: join2(dir, "daemon.log")
   };
 }
+function resolveDaemonVersionFromEnv(env = process.env) {
+  const version = env[CODEX_LSP_DAEMON_VERSION_ENV]?.trim();
+  return version && version.length > 0 ? version : null;
+}
 function resolveSocketPath(dir, version) {
   const digest = createHash("sha256").update(dir).digest("hex").slice(0, 16);
   if (process.platform === "win32") {

package/packages/lsp-daemon/dist/paths.d.ts

@@ -9,3 +9,4 @@ export interface DaemonPaths {
 export declare function resolveDaemonVersion(requireFn?: (id: string) => unknown): string;
 export declare function daemonBaseDir(env?: NodeJS.ProcessEnv): string;
 export declare function daemonPaths(env?: NodeJS.ProcessEnv, version?: string): DaemonPaths;
+export declare function resolveDaemonVersionFromEnv(env?: NodeJS.ProcessEnv): string | null;

package/packages/lsp-daemon/dist/paths.js

@@ -4,6 +4,7 @@ import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 const requireFromHere = createRequire(import.meta.url);
 const MAX_SOCKET_PATH_LENGTH = 100;
+const CODEX_LSP_DAEMON_VERSION_ENV = "CODEX_LSP_DAEMON_VERSION";
 export function resolveDaemonVersion(requireFn = requireFromHere) {
     for (const candidate of ["./package.json", "../package.json"]) {
         try {
@@ -26,7 +27,7 @@ export function daemonBaseDir(env = process.env) {
     const home = codexHome && codexHome.length > 0 ? codexHome : join(homedir(), ".codex");
     return join(home, "codex-lsp", "daemon");
 }
-export function daemonPaths(env = process.env, version = resolveDaemonVersion()) {
+export function daemonPaths(env = process.env, version = resolveDaemonVersionFromEnv(env) ?? resolveDaemonVersion()) {
     const dir = join(daemonBaseDir(env), `v${version}`);
     return {
         version,
@@ -37,6 +38,10 @@ export function daemonPaths(env = process.env, version = resolveDaemonVersion())
         log: join(dir, "daemon.log"),
     };
 }
+export function resolveDaemonVersionFromEnv(env = process.env) {
+    const version = env[CODEX_LSP_DAEMON_VERSION_ENV]?.trim();
+    return version && version.length > 0 ? version : null;
+}
 function resolveSocketPath(dir, version) {
     const digest = createHash("sha256").update(dir).digest("hex").slice(0, 16);
     if (process.platform === "win32") {

package/packages/omo-codex/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "omo",
-  "version": "4.14.0",
+  "version": "4.14.1",
   "description": "One Codex plugin namespace for Yeongyu's local Codex components.",
   "author": {
     "name": "Yeongyu Kim",

package/packages/omo-codex/plugin/components/bootstrap/dist/cli.js

@@ -1307,10 +1307,9 @@ function posixRuntimeWrapper(cliPath, codexHome, binDir, nodeCliPath) {
     "#!/bin/sh",
     `# ${RUNTIME_WRAPPER_MARKER}`,
     `export CODEX_HOME="\${CODEX_HOME:-${escapedCodexHome}}"`,
-    'export OMO_SPARKSHELL_APP_SERVER_SOCKET="${OMO_SPARKSHELL_APP_SERVER_SOCKET:-$CODEX_HOME/app-server-control/app-server-control.sock}"',
     'if [ "$1" = "ulw-loop" ] && [ -x "' + escapedUlwLoopBin + '" ]; then',
     "  shift",
-    '  exec "' + escapedUlwLoopBin + '" "$@"',
+    '  exec "' + escapedUlwLoopBin + '" ulw-loop "$@"',
     "fi",
     `if [ "\${OMO_RUNTIME:-}" = "node" ] && [ -f "${nodeCli}" ]; then`,
     `  exec node "${nodeCli}" "$@"`,
@@ -1349,11 +1348,10 @@ function windowsRuntimeWrapper(cliPath, codexHome, binDir, nodeCliPath) {
     "@echo off",
     `rem ${RUNTIME_WRAPPER_MARKER}`,
     `if not defined CODEX_HOME set "CODEX_HOME=${codexHome}"`,
-    'if not defined OMO_SPARKSHELL_APP_SERVER_SOCKET set "OMO_SPARKSHELL_APP_SERVER_SOCKET=%CODEX_HOME%\\app-server-control\\app-server-control.sock"',
     ...windowsNodeDiscoveryLines(),
     `if "%~1"=="ulw-loop" if exist "${ulwLoopBin}" (`,
     "  shift /1",
-    `  "${ulwLoopBin}" %*`,
+    `  "${ulwLoopBin}" ulw-loop %*`,
     "  exit /b %ERRORLEVEL%",
     ")",
     `if "%OMO_RUNTIME%"=="node" if defined OMO_NODE_BINARY if exist "${nodeCliPath}" (`,
@@ -2050,7 +2048,7 @@ function ensureMarketplaceBlock(config, marketplaceName, source) {
 }
 
 // ../src/install/codex-config-permissions.ts
-var AUTONOMOUS_FEATURES = ["multi_agent", "child_agents_md", "unified_exec", "goals"];
+var AUTONOMOUS_FEATURES = ["multi_agent", "unified_exec", "goals"];
 function ensureAutonomousPermissions(config) {
   let next = replaceOrInsertRootSetting(config, "approval_policy", JSON.stringify("never"));
   next = replaceOrInsertRootSetting(next, "sandbox_mode", JSON.stringify("danger-full-access"));
@@ -2470,7 +2468,6 @@ async function updateCodexConfig(input) {
   config = ensureFeatureEnabled(config, "plugins");
   config = ensureFeatureEnabled(config, "plugin_hooks");
   config = ensureFeatureEnabled(config, "multi_agent");
-  config = ensureFeatureEnabled(config, "child_agents_md");
   config = removeUnsupportedCodexMultiAgentModeConfig(config);
   config = ensureCodexReasoningConfig(config, await readCodexModelCatalog(input.repoRoot));
   config = ensureCodexMultiAgentV2Config(config);
@@ -2947,7 +2944,7 @@ async function linkRuntimeWrapperStep(options, binDir, degraded) {
       reason: "marketplace payload has no dist/cli"
     });
     await appendBootstrapLog(options.pluginData, options.now ?? Date.now(), "omo-cli-degraded", {
-      warning: `Warning: skipped the omo runtime wrapper because ${cliPath} is missing; omo sparkshell/ulw-loop commands will be unavailable until a package shipping dist/cli is installed`
+      warning: `Warning: skipped the omo runtime wrapper because ${cliPath} is missing; omo ulw-loop commands will be unavailable until a package shipping dist/cli is installed`
     });
   } catch (error) {
     degraded.push({

package/packages/omo-codex/plugin/components/bootstrap/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sisyphuslabs/codex-bootstrap",
-	"version": "4.14.0",
+	"version": "4.14.1",
 	"description": "Codex SessionStart bootstrap component that provisions LazyCodex runtime dependencies from a detached worker.",
 	"type": "module",
 	"private": true,

package/packages/omo-codex/plugin/components/bootstrap/src/setup.ts

@@ -225,7 +225,7 @@ async function linkRuntimeWrapperStep(
 			reason: "marketplace payload has no dist/cli",
 		});
 		await appendBootstrapLog(options.pluginData, options.now ?? Date.now(), "omo-cli-degraded", {
-			warning: `Warning: skipped the omo runtime wrapper because ${cliPath} is missing; omo sparkshell/ulw-loop commands will be unavailable until a package shipping dist/cli is installed`,
+			warning: `Warning: skipped the omo runtime wrapper because ${cliPath} is missing; omo ulw-loop commands will be unavailable until a package shipping dist/cli is installed`,
 		});
 	} catch (error) {
 		degraded.push({

package/packages/omo-codex/plugin/components/codegraph/dist/cli.js

@@ -2589,6 +2589,9 @@ class CodegraphBridgeStdioError extends Error {
     this.streamName = streamName;
   }
 }
+var CODEGRAPH_NODE_DESCRIPTION = "Inspect one named symbol or file. In symbol mode, includeCode=true includes leaf-symbol source when available. Container symbols such as classes, interfaces, structs, enums, modules, and namespaces return structural outlines with member lists by design. For container source, request a specific member symbol or use file mode with symbolsOnly=false plus offset/limit.";
+var CODEGRAPH_NODE_INCLUDE_CODE_DESCRIPTION = "Symbol mode: include leaf-symbol source when available. Container symbols such as classes, interfaces, structs, enums, modules, and namespaces intentionally return structural outlines with members; request a specific member symbol or use file mode with symbolsOnly=false plus offset/limit for source.";
+var CODEGRAPH_CONTAINER_OUTLINE_GUIDANCE = "Container symbols intentionally return structural outlines with members. For source, request a specific member symbol or call codegraph_node in file mode with symbolsOnly=false plus offset/limit around the symbol location.";
 async function runBridgedCodegraphProcess(command, args, options) {
   const invocation = resolveServeProcessInvocation(command, args);
   const child = spawn2(invocation.command, invocation.args, {
@@ -2602,7 +2605,7 @@ async function runBridgedCodegraphProcess(command, args, options) {
     throw new CodegraphBridgeStdioError("stdin");
   if (childOutput === null)
     throw new CodegraphBridgeStdioError("stdout");
-  const responseModes = new Map;
+  const pendingResponses = new Map;
   let defaultResponseMode = "framed";
   const childExit = new Promise((resolveExit, reject) => {
     child.once("error", reject);
@@ -2615,10 +2618,10 @@ async function runBridgedCodegraphProcess(command, args, options) {
     });
   });
   const bridgeDone = Promise.all([
-    forwardClientToCodegraph(options.input, childInput, responseModes, (mode) => {
+    forwardClientToCodegraph(options.input, childInput, pendingResponses, (mode) => {
       defaultResponseMode = mode;
     }),
-    forwardCodegraphToClient(childOutput, options.output, responseModes, () => defaultResponseMode)
+    forwardCodegraphToClient(childOutput, options.output, pendingResponses, () => defaultResponseMode)
   ]);
   const destroyChildPipes = () => {
     childInput.destroy();
@@ -2627,7 +2630,7 @@ async function runBridgedCodegraphProcess(command, args, options) {
   childExit.then(destroyChildPipes, destroyChildPipes);
   return Promise.race([childExit, bridgeDone.then(() => childExit)]);
 }
-async function forwardClientToCodegraph(input, childInput, responseModes, setDefaultResponseMode) {
+async function forwardClientToCodegraph(input, childInput, pendingResponses, setDefaultResponseMode) {
   for await (const message of readStdioJsonRpcMessages(input)) {
     if (message.kind === "parse_error") {
       continue;
@@ -2635,23 +2638,29 @@ async function forwardClientToCodegraph(input, childInput, responseModes, setDef
     const responseMode = message.responseMode;
     setDefaultResponseMode(responseMode);
     const key = responseModeKey(message.payload);
-    if (key !== null)
-      responseModes.set(key, responseMode);
+    if (key !== null) {
+      pendingResponses.set(key, {
+        method: jsonRpcMethod(message.payload),
+        responseMode,
+        toolName: jsonRpcToolName(message.payload)
+      });
+    }
     await writeLine(childInput, JSON.stringify(message.payload));
   }
   childInput.end();
 }
-async function forwardCodegraphToClient(childOutput, output, responseModes, defaultResponseMode) {
+async function forwardCodegraphToClient(childOutput, output, pendingResponses, defaultResponseMode) {
   for await (const message of readStdioJsonRpcMessages(childOutput)) {
     if (message.kind === "parse_error") {
       writeStdioJsonRpcResponse(output, errorResponse(null, -32700, "Parse error", message.message), defaultResponseMode());
       continue;
     }
     const key = responseModeKey(message.payload);
-    const responseMode = key === null ? defaultResponseMode() : responseModes.get(key) ?? defaultResponseMode();
+    const pendingResponse = key === null ? undefined : pendingResponses.get(key);
+    const responseMode = pendingResponse?.responseMode ?? defaultResponseMode();
     if (key !== null)
-      responseModes.delete(key);
-    writeStdioJsonRpcResponse(output, message.payload, responseMode);
+      pendingResponses.delete(key);
+    writeStdioJsonRpcResponse(output, clarifyCodegraphResponse(message.payload, pendingResponse), responseMode);
   }
 }
 function responseModeKey(payload) {
@@ -2660,6 +2669,110 @@ function responseModeKey(payload) {
   const id = jsonRpcId(payload["id"]);
   return `${typeof id}:${String(id)}`;
 }
+function jsonRpcMethod(payload) {
+  if (!isPlainRecord(payload))
+    return null;
+  const method = payload["method"];
+  return typeof method === "string" ? method : null;
+}
+function jsonRpcToolName(payload) {
+  if (jsonRpcMethod(payload) !== "tools/call" || !isPlainRecord(payload))
+    return null;
+  const params = payload["params"];
+  if (!isPlainRecord(params))
+    return null;
+  const name = params["name"];
+  return typeof name === "string" ? name : null;
+}
+function clarifyCodegraphResponse(payload, pendingResponse) {
+  if (pendingResponse?.method === "tools/list")
+    return clarifyCodegraphToolsList(payload);
+  if (pendingResponse?.method === "tools/call" && pendingResponse.toolName === "codegraph_node") {
+    return clarifyCodegraphNodeCallResult(payload);
+  }
+  return payload;
+}
+function clarifyCodegraphToolsList(payload) {
+  if (!isPlainRecord(payload))
+    return payload;
+  const result = payload["result"];
+  if (!isPlainRecord(result) || !Array.isArray(result["tools"]))
+    return payload;
+  let changed = false;
+  const tools = result["tools"].map((tool) => {
+    if (!isPlainRecord(tool) || tool["name"] !== "codegraph_node")
+      return tool;
+    if (!hasCodegraphNodeContractMetadata(tool))
+      return tool;
+    changed = true;
+    return clarifyCodegraphNodeTool(tool);
+  });
+  if (!changed)
+    return payload;
+  return { ...payload, result: { ...result, tools } };
+}
+function clarifyCodegraphNodeTool(tool) {
+  const clarified = {
+    ...tool,
+    description: CODEGRAPH_NODE_DESCRIPTION
+  };
+  const inputSchema = tool["inputSchema"];
+  if (isPlainRecord(inputSchema))
+    clarified["inputSchema"] = clarifyCodegraphNodeInputSchema(inputSchema);
+  return clarified;
+}
+function hasCodegraphNodeContractMetadata(tool) {
+  if (typeof tool["description"] === "string")
+    return true;
+  const inputSchema = tool["inputSchema"];
+  if (!isPlainRecord(inputSchema))
+    return false;
+  const properties = inputSchema["properties"];
+  return isPlainRecord(properties) && isPlainRecord(properties["includeCode"]);
+}
+function clarifyCodegraphNodeInputSchema(inputSchema) {
+  const properties = inputSchema["properties"];
+  if (!isPlainRecord(properties))
+    return inputSchema;
+  const includeCode = properties["includeCode"];
+  if (!isPlainRecord(includeCode))
+    return inputSchema;
+  return {
+    ...inputSchema,
+    properties: {
+      ...properties,
+      includeCode: {
+        ...includeCode,
+        description: CODEGRAPH_NODE_INCLUDE_CODE_DESCRIPTION
+      }
+    }
+  };
+}
+function clarifyCodegraphNodeCallResult(payload) {
+  if (!isPlainRecord(payload))
+    return payload;
+  const result = payload["result"];
+  if (!isPlainRecord(result) || !Array.isArray(result["content"]))
+    return payload;
+  let changed = false;
+  const content = result["content"].map((item) => {
+    if (!isPlainRecord(item) || item["type"] !== "text" || typeof item["text"] !== "string")
+      return item;
+    const text = clarifyContainerOutlineGuidance(item["text"]);
+    if (text === item["text"])
+      return item;
+    changed = true;
+    return { ...item, text };
+  });
+  if (!changed)
+    return payload;
+  return { ...payload, result: { ...result, content } };
+}
+function clarifyContainerOutlineGuidance(text) {
+  if (!text.includes("Structural outline only"))
+    return text;
+  return text.replace(/Structural outline only[^\n]*(?:\n[^\n]*(?:Read|read)[^\n]*)?/g, CODEGRAPH_CONTAINER_OUTLINE_GUIDANCE);
+}
 async function writeLine(output, line) {
   if (output.write(`${line}
 `))

package/packages/omo-codex/plugin/components/codegraph/dist/serve.js

@@ -2022,6 +2022,9 @@ class CodegraphBridgeStdioError extends Error {
     this.streamName = streamName;
   }
 }
+var CODEGRAPH_NODE_DESCRIPTION = "Inspect one named symbol or file. In symbol mode, includeCode=true includes leaf-symbol source when available. Container symbols such as classes, interfaces, structs, enums, modules, and namespaces return structural outlines with member lists by design. For container source, request a specific member symbol or use file mode with symbolsOnly=false plus offset/limit.";
+var CODEGRAPH_NODE_INCLUDE_CODE_DESCRIPTION = "Symbol mode: include leaf-symbol source when available. Container symbols such as classes, interfaces, structs, enums, modules, and namespaces intentionally return structural outlines with members; request a specific member symbol or use file mode with symbolsOnly=false plus offset/limit for source.";
+var CODEGRAPH_CONTAINER_OUTLINE_GUIDANCE = "Container symbols intentionally return structural outlines with members. For source, request a specific member symbol or call codegraph_node in file mode with symbolsOnly=false plus offset/limit around the symbol location.";
 async function runBridgedCodegraphProcess(command, args, options) {
   const invocation = resolveServeProcessInvocation(command, args);
   const child = spawn(invocation.command, invocation.args, {
@@ -2035,7 +2038,7 @@ async function runBridgedCodegraphProcess(command, args, options) {
     throw new CodegraphBridgeStdioError("stdin");
   if (childOutput === null)
     throw new CodegraphBridgeStdioError("stdout");
-  const responseModes = new Map;
+  const pendingResponses = new Map;
   let defaultResponseMode = "framed";
   const childExit = new Promise((resolveExit, reject) => {
     child.once("error", reject);
@@ -2048,10 +2051,10 @@ async function runBridgedCodegraphProcess(command, args, options) {
     });
   });
   const bridgeDone = Promise.all([
-    forwardClientToCodegraph(options.input, childInput, responseModes, (mode) => {
+    forwardClientToCodegraph(options.input, childInput, pendingResponses, (mode) => {
       defaultResponseMode = mode;
     }),
-    forwardCodegraphToClient(childOutput, options.output, responseModes, () => defaultResponseMode)
+    forwardCodegraphToClient(childOutput, options.output, pendingResponses, () => defaultResponseMode)
   ]);
   const destroyChildPipes = () => {
     childInput.destroy();
@@ -2060,7 +2063,7 @@ async function runBridgedCodegraphProcess(command, args, options) {
   childExit.then(destroyChildPipes, destroyChildPipes);
   return Promise.race([childExit, bridgeDone.then(() => childExit)]);
 }
-async function forwardClientToCodegraph(input, childInput, responseModes, setDefaultResponseMode) {
+async function forwardClientToCodegraph(input, childInput, pendingResponses, setDefaultResponseMode) {
   for await (const message of readStdioJsonRpcMessages(input)) {
     if (message.kind === "parse_error") {
       continue;
@@ -2068,23 +2071,29 @@ async function forwardClientToCodegraph(input, childInput, responseModes, setDef
     const responseMode = message.responseMode;
     setDefaultResponseMode(responseMode);
     const key = responseModeKey(message.payload);
-    if (key !== null)
-      responseModes.set(key, responseMode);
+    if (key !== null) {
+      pendingResponses.set(key, {
+        method: jsonRpcMethod(message.payload),
+        responseMode,
+        toolName: jsonRpcToolName(message.payload)
+      });
+    }
     await writeLine(childInput, JSON.stringify(message.payload));
   }
   childInput.end();
 }
-async function forwardCodegraphToClient(childOutput, output, responseModes, defaultResponseMode) {
+async function forwardCodegraphToClient(childOutput, output, pendingResponses, defaultResponseMode) {
   for await (const message of readStdioJsonRpcMessages(childOutput)) {
     if (message.kind === "parse_error") {
       writeStdioJsonRpcResponse(output, errorResponse(null, -32700, "Parse error", message.message), defaultResponseMode());
       continue;
     }
     const key = responseModeKey(message.payload);
-    const responseMode = key === null ? defaultResponseMode() : responseModes.get(key) ?? defaultResponseMode();
+    const pendingResponse = key === null ? undefined : pendingResponses.get(key);
+    const responseMode = pendingResponse?.responseMode ?? defaultResponseMode();
     if (key !== null)
-      responseModes.delete(key);
-    writeStdioJsonRpcResponse(output, message.payload, responseMode);
+      pendingResponses.delete(key);
+    writeStdioJsonRpcResponse(output, clarifyCodegraphResponse(message.payload, pendingResponse), responseMode);
   }
 }
 function responseModeKey(payload) {
@@ -2093,6 +2102,110 @@ function responseModeKey(payload) {
   const id = jsonRpcId(payload["id"]);
   return `${typeof id}:${String(id)}`;
 }
+function jsonRpcMethod(payload) {
+  if (!isPlainRecord(payload))
+    return null;
+  const method = payload["method"];
+  return typeof method === "string" ? method : null;
+}
+function jsonRpcToolName(payload) {
+  if (jsonRpcMethod(payload) !== "tools/call" || !isPlainRecord(payload))
+    return null;
+  const params = payload["params"];
+  if (!isPlainRecord(params))
+    return null;
+  const name = params["name"];
+  return typeof name === "string" ? name : null;
+}
+function clarifyCodegraphResponse(payload, pendingResponse) {
+  if (pendingResponse?.method === "tools/list")
+    return clarifyCodegraphToolsList(payload);
+  if (pendingResponse?.method === "tools/call" && pendingResponse.toolName === "codegraph_node") {
+    return clarifyCodegraphNodeCallResult(payload);
+  }
+  return payload;
+}
+function clarifyCodegraphToolsList(payload) {
+  if (!isPlainRecord(payload))
+    return payload;
+  const result = payload["result"];
+  if (!isPlainRecord(result) || !Array.isArray(result["tools"]))
+    return payload;
+  let changed = false;
+  const tools = result["tools"].map((tool) => {
+    if (!isPlainRecord(tool) || tool["name"] !== "codegraph_node")
+      return tool;
+    if (!hasCodegraphNodeContractMetadata(tool))
+      return tool;
+    changed = true;
+    return clarifyCodegraphNodeTool(tool);
+  });
+  if (!changed)
+    return payload;
+  return { ...payload, result: { ...result, tools } };
+}
+function clarifyCodegraphNodeTool(tool) {
+  const clarified = {
+    ...tool,
+    description: CODEGRAPH_NODE_DESCRIPTION
+  };
+  const inputSchema = tool["inputSchema"];
+  if (isPlainRecord(inputSchema))
+    clarified["inputSchema"] = clarifyCodegraphNodeInputSchema(inputSchema);
+  return clarified;
+}
+function hasCodegraphNodeContractMetadata(tool) {
+  if (typeof tool["description"] === "string")
+    return true;
+  const inputSchema = tool["inputSchema"];
+  if (!isPlainRecord(inputSchema))
+    return false;
+  const properties = inputSchema["properties"];
+  return isPlainRecord(properties) && isPlainRecord(properties["includeCode"]);
+}
+function clarifyCodegraphNodeInputSchema(inputSchema) {
+  const properties = inputSchema["properties"];
+  if (!isPlainRecord(properties))
+    return inputSchema;
+  const includeCode = properties["includeCode"];
+  if (!isPlainRecord(includeCode))
+    return inputSchema;
+  return {
+    ...inputSchema,
+    properties: {
+      ...properties,
+      includeCode: {
+        ...includeCode,
+        description: CODEGRAPH_NODE_INCLUDE_CODE_DESCRIPTION
+      }
+    }
+  };
+}
+function clarifyCodegraphNodeCallResult(payload) {
+  if (!isPlainRecord(payload))
+    return payload;
+  const result = payload["result"];
+  if (!isPlainRecord(result) || !Array.isArray(result["content"]))
+    return payload;
+  let changed = false;
+  const content = result["content"].map((item) => {
+    if (!isPlainRecord(item) || item["type"] !== "text" || typeof item["text"] !== "string")
+      return item;
+    const text = clarifyContainerOutlineGuidance(item["text"]);
+    if (text === item["text"])
+      return item;
+    changed = true;
+    return { ...item, text };
+  });
+  if (!changed)
+    return payload;
+  return { ...payload, result: { ...result, content } };
+}
+function clarifyContainerOutlineGuidance(text) {
+  if (!text.includes("Structural outline only"))
+    return text;
+  return text.replace(/Structural outline only[^\n]*(?:\n[^\n]*(?:Read|read)[^\n]*)?/g, CODEGRAPH_CONTAINER_OUTLINE_GUIDANCE);
+}
 async function writeLine(output, line) {
   if (output.write(`${line}
 `))

package/packages/omo-codex/plugin/components/codegraph/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sisyphuslabs/codex-codegraph",
-	"version": "4.14.0",
+	"version": "4.14.1",
 	"description": "Codex plugin MCP wrapper for CodeGraph.",
 	"type": "module",
 	"private": true,