oh-my-opencode 4.13.0 → 4.14.1

package/packages/omo-codex/plugin/components/codegraph/src/mcp-bridge.ts

@@ -0,0 +1,231 @@
+import { spawn } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+
+import {
+	errorResponse,
+	isPlainRecord,
+	jsonRpcId,
+	readStdioJsonRpcMessages,
+	writeStdioJsonRpcResponse,
+	type StdioJsonRpcResponseMode,
+} from "../../../../../mcp-stdio-core/src/index.ts";
+import type { CodegraphServeProcessOptions } from "./serve.js";
+import { resolveServeProcessInvocation } from "./serve-invocation.js";
+
+class CodegraphBridgeStdioError extends Error {
+	override readonly name = "CodegraphBridgeStdioError";
+
+	constructor(readonly streamName: string) {
+		super(`CodeGraph MCP bridge missing child ${streamName}`);
+	}
+}
+
+interface PendingClientResponse {
+	readonly method: string | null;
+	readonly responseMode: StdioJsonRpcResponseMode;
+	readonly toolName: string | null;
+}
+
+const 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.";
+
+const 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.";
+
+const 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.";
+
+export async function runBridgedCodegraphProcess(
+	command: string,
+	args: readonly string[],
+	options: CodegraphServeProcessOptions,
+): Promise<number> {
+	const invocation = resolveServeProcessInvocation(command, args);
+	const child = spawn(invocation.command, invocation.args, {
+		cwd: options.cwd,
+		env: options.env,
+		stdio: ["pipe", "pipe", "inherit"],
+	});
+	const childInput = child.stdin;
+	const childOutput = child.stdout;
+	if (childInput === null) throw new CodegraphBridgeStdioError("stdin");
+	if (childOutput === null) throw new CodegraphBridgeStdioError("stdout");
+
+	const pendingResponses = new Map<string, PendingClientResponse>();
+	let defaultResponseMode: StdioJsonRpcResponseMode = "framed";
+	const childExit = new Promise<number>((resolveExit, reject) => {
+		child.once("error", reject);
+		child.once("exit", (code, signal) => {
+			if (code !== null) {
+				resolveExit(code);
+				return;
+			}
+			resolveExit(signal === null ? 0 : 1);
+		});
+	});
+	const bridgeDone = Promise.all([
+		forwardClientToCodegraph(options.input, childInput, pendingResponses, (mode) => {
+			defaultResponseMode = mode;
+		}),
+		forwardCodegraphToClient(childOutput, options.output, pendingResponses, () => defaultResponseMode),
+	]);
+	const destroyChildPipes = (): void => {
+		childInput.destroy();
+		childOutput.destroy();
+	};
+	void childExit.then(destroyChildPipes, destroyChildPipes);
+	return Promise.race([childExit, bridgeDone.then(() => childExit)]);
+}
+
+async function forwardClientToCodegraph(
+	input: Readable,
+	childInput: Writable,
+	pendingResponses: Map<string, PendingClientResponse>,
+	setDefaultResponseMode: (mode: StdioJsonRpcResponseMode) => void,
+): Promise<void> {
+	for await (const message of readStdioJsonRpcMessages(input)) {
+		if (message.kind === "parse_error") {
+			continue;
+		}
+		const responseMode = message.responseMode;
+		setDefaultResponseMode(responseMode);
+		const key = responseModeKey(message.payload);
+		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: Readable,
+	output: Writable,
+	pendingResponses: Map<string, PendingClientResponse>,
+	defaultResponseMode: () => StdioJsonRpcResponseMode,
+): Promise<void> {
+	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 pendingResponse = key === null ? undefined : pendingResponses.get(key);
+		const responseMode = pendingResponse?.responseMode ?? defaultResponseMode();
+		if (key !== null) pendingResponses.delete(key);
+		writeStdioJsonRpcResponse(output, clarifyCodegraphResponse(message.payload, pendingResponse), responseMode);
+	}
+}
+
+function responseModeKey(payload: unknown): string | null {
+	if (!isPlainRecord(payload) || !("id" in payload)) return null;
+	const id = jsonRpcId(payload["id"]);
+	return `${typeof id}:${String(id)}`;
+}
+
+function jsonRpcMethod(payload: unknown): string | null {
+	if (!isPlainRecord(payload)) return null;
+	const method = payload["method"];
+	return typeof method === "string" ? method : null;
+}
+
+function jsonRpcToolName(payload: unknown): string | null {
+	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: unknown, pendingResponse: PendingClientResponse | undefined): unknown {
+	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: unknown): unknown {
+	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: Record<string, unknown>): Record<string, unknown> {
+	const clarified: Record<string, unknown> = {
+		...tool,
+		description: CODEGRAPH_NODE_DESCRIPTION,
+	};
+	const inputSchema = tool["inputSchema"];
+	if (isPlainRecord(inputSchema)) clarified["inputSchema"] = clarifyCodegraphNodeInputSchema(inputSchema);
+	return clarified;
+}
+
+function hasCodegraphNodeContractMetadata(tool: Record<string, unknown>): boolean {
+	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: Record<string, unknown>): Record<string, unknown> {
+	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: unknown): unknown {
+	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: string): string {
+	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: Writable, line: string): Promise<void> {
+	if (output.write(`${line}\n`)) return;
+	await new Promise<void>((resolveDrain, reject) => {
+		output.once("drain", resolveDrain);
+		output.once("error", reject);
+	});
+}

package/packages/omo-codex/plugin/components/codegraph/src/serve-invocation.ts

@@ -0,0 +1,29 @@
+import { extname } from "node:path";
+import { execPath as processExecPath } from "node:process";
+
+export interface ServeProcessInvocation {
+	readonly args: readonly string[];
+	readonly command: string;
+}
+
+const WINDOWS_CMD_EXTENSIONS = new Set([".bat", ".cmd"]);
+const WINDOWS_NODE_SCRIPT_EXTENSIONS = new Set([".cjs", ".js", ".mjs"]);
+
+export function resolveServeProcessInvocation(
+	command: string,
+	args: readonly string[],
+	platform: NodeJS.Platform = process.platform,
+): ServeProcessInvocation {
+	if (platform !== "win32") return { args: [...args], command };
+
+	const extension = extname(command).toLowerCase();
+	if (WINDOWS_NODE_SCRIPT_EXTENSIONS.has(extension)) {
+		return { args: [command, ...args], command: processExecPath };
+	}
+
+	if (WINDOWS_CMD_EXTENSIONS.has(extension)) {
+		return { args: ["/d", "/s", "/c", command, ...args], command: "cmd.exe" };
+	}
+
+	return { args: [...args], command };
+}

package/packages/omo-codex/plugin/components/codegraph/src/serve.ts

@@ -1,12 +1,10 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, extname, join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import {
 	cwd as processCwd,
 	env as processEnv,
-	execPath as processExecPath,
 	stdin as processStdin,
 	stderr as processStderr,
 	stdout as processStdout,
@@ -14,7 +12,7 @@ import {
 import type { Readable, Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
 
-import { buildCodegraphEnv } from "../../../../../utils/src/codegraph/env.ts";
+import { buildCodegraphChildEnv, buildCodegraphEnv } from "../../../../../utils/src/codegraph/env.ts";
 import {
 	buildCodegraphNodeSkipHint,
 	evaluateCodegraphNodeSupport,
@@ -31,12 +29,19 @@ import {
 } from "../../../../../utils/src/codegraph/resolve.ts";
 import { getCodexOmoConfig, type CodexOmoConfig } from "../../../shared/src/config-loader.ts";
 import type { CodegraphConfig } from "./hook.js";
+import { runBridgedCodegraphProcess } from "./mcp-bridge.js";
 import { runUnavailableCodegraphMcpServer } from "./mcp-unavailable.js";
+import { SESSION_START_CWD_ENV } from "./session-start-worker.js";
+export { resolveServeProcessInvocation } from "./serve-invocation.js";
 
-export type ServeStdio = "inherit";
+export type ServeStdio = "pipe";
 
 export interface CodegraphServeProcessOptions {
+	readonly cwd: string;
 	readonly env: Record<string, string | undefined>;
+	readonly input: Readable;
+	readonly output: Writable;
+	readonly stderr: CodegraphServeStderr;
 	readonly stdio: ServeStdio;
 }
 
@@ -49,11 +54,6 @@ export type CodegraphProvisioner = (
 	options: EnsureCodegraphProvisionedOptions,
 ) => ReturnType<typeof ensureCodegraphProvisioned>;
 
-export interface ServeProcessInvocation {
-	readonly args: readonly string[];
-	readonly command: string;
-}
-
 export interface CodegraphServeStderr {
 	readonly write: (chunk: string) => void;
 }
@@ -79,13 +79,14 @@ const CODEGRAPH_SKIP_HINT =
 const CODEGRAPH_DISABLED_HINT =
 	"CodeGraph MCP skipped: disabled by OMO SOT config. Set [codex].codegraph.enabled=true to enable it.\n";
 const CODEGRAPH_VERSION = "1.0.1";
-const WINDOWS_CMD_EXTENSIONS = new Set([".bat", ".cmd"]);
-const WINDOWS_NODE_SCRIPT_EXTENSIONS = new Set([".cjs", ".js", ".mjs"]);
+const PROJECT_CWD_ENV_KEYS = ["OMO_CODEGRAPH_PROJECT_CWD", SESSION_START_CWD_ENV, "PWD"] as const;
 
 export async function runCodegraphServe(options: RunCodegraphServeOptions = {}): Promise<number> {
 	const env = options.env ?? processEnv;
 	const homeDir = options.homeDir ?? homedir();
-	const config = options.config ?? getCodexOmoConfig({ cwd: options.cwd ?? processCwd(), env, homeDir });
+	const wrapperCwd = options.cwd ?? processCwd();
+	const projectCwd = resolveProjectCwd(env, wrapperCwd);
+	const config = options.config ?? getCodexOmoConfig({ cwd: projectCwd, env, homeDir });
 	const codegraphConfig = config.codegraph ?? {};
 	if (codegraphConfig.enabled === false) {
 		return runUnavailableMcp(CODEGRAPH_DISABLED_HINT, options);
@@ -120,15 +121,16 @@ export async function runCodegraphServe(options: RunCodegraphServeOptions = {}):
 		return runUnavailableMcp(buildCodegraphNodeSkipHint(nodeSupport), options);
 	}
 
-	const runProcess = options.runProcess ?? runChildProcess;
+	const runProcess = options.runProcess ?? runBridgedCodegraphProcess;
 	const codegraphEnv = codegraphEnvForConfig(trustedInstallDir, homeDir, options.buildEnv);
-	const mergedEnv = {
-		...env,
-		...codegraphEnv,
-	};
+	const mergedEnv = buildCodegraphChildEnv({ ambientEnv: env, codegraphEnv, runtimeEnv: env });
 	return runProcess(resolution.command, [...resolution.argsPrefix, "serve", "--mcp"], {
+		cwd: projectCwd,
 		env: mergedEnv,
-		stdio: "inherit",
+		input: options.stdin ?? processStdin,
+		output: options.stdout ?? processStdout,
+		stderr: options.stderr ?? processStderr,
+		stdio: "pipe",
 	});
 }
 
@@ -185,6 +187,16 @@ function codegraphEnvForConfig(
 	return trustedInstallDir === undefined ? env : { ...env, CODEGRAPH_INSTALL_DIR: trustedInstallDir };
 }
 
+function resolveProjectCwd(env: Record<string, string | undefined>, fallback: string): string {
+	for (const key of PROJECT_CWD_ENV_KEYS) {
+		const candidate = env[key]?.trim();
+		if (candidate === undefined || candidate.length === 0) continue;
+		const resolved = resolve(candidate);
+		if (existsSync(resolved)) return resolved;
+	}
+	return resolve(fallback);
+}
+
 function provisionedBinFromInstallDir(installDir: string | undefined): string | null {
 	if (installDir === undefined) return null;
 	const candidate = join(installDir, "bin", process.platform === "win32" ? "codegraph.cmd" : "codegraph");
@@ -195,44 +207,6 @@ export async function runCodegraphServeCli(): Promise<void> {
 	process.exitCode = await runCodegraphServe();
 }
 
-async function runChildProcess(
-	command: string,
-	args: readonly string[],
-	options: CodegraphServeProcessOptions,
-): Promise<number> {
-	const invocation = resolveServeProcessInvocation(command, args);
-	const child = spawn(invocation.command, invocation.args, { env: options.env, stdio: options.stdio });
-	return new Promise<number>((resolve, reject) => {
-		child.once("error", reject);
-		child.once("exit", (code, signal) => {
-			if (code !== null) {
-				resolve(code);
-				return;
-			}
-			resolve(signal === null ? 0 : 1);
-		});
-	});
-}
-
-export function resolveServeProcessInvocation(
-	command: string,
-	args: readonly string[],
-	platform: NodeJS.Platform = process.platform,
-): ServeProcessInvocation {
-	if (platform !== "win32") return { args: [...args], command };
-
-	const extension = extname(command).toLowerCase();
-	if (WINDOWS_NODE_SCRIPT_EXTENSIONS.has(extension)) {
-		return { args: [command, ...args], command: processExecPath };
-	}
-
-	if (WINDOWS_CMD_EXTENSIONS.has(extension)) {
-		return { args: ["/d", "/s", "/c", command, ...args], command: "cmd.exe" };
-	}
-
-	return { args: [...args], command };
-}
-
 if (isDirectInvocation(process.argv[1])) {
 	runCodegraphServeCli().catch((error: unknown) => {
 		processStderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);

package/packages/omo-codex/plugin/components/codegraph/src/session-start-worker.ts

@@ -2,10 +2,10 @@ import { execFile } from "node:child_process";
 import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { extname, join } from "node:path";
-import { cwd as processCwd, env as processEnv, stderr as processStderr } from "node:process";
+import { cwd as processCwd, env as processEnv, execPath as processExecPath, stderr as processStderr } from "node:process";
 
 import { getCodexOmoConfig } from "../../../shared/src/config-loader.ts";
-import { buildCodegraphEnv } from "../../../../../utils/src/codegraph/env.ts";
+import { buildCodegraphChildEnv, buildCodegraphEnv } from "../../../../../utils/src/codegraph/env.ts";
 import { evaluateCodegraphNodeSupport, type CodegraphNodeSupport } from "../../../../../utils/src/codegraph/node-support.ts";
 import { ensureCodegraphProvisioned } from "../../../../../utils/src/codegraph/provision.ts";
 import {
@@ -28,6 +28,7 @@ export const SESSION_START_CWD_ENV = "OMO_CODEGRAPH_SESSION_START_CWD";
 const CODEGRAPH_VERSION = "1.0.1";
 const COMMAND_TIMEOUT_MS = 60_000;
 const WINDOWS_CMD_EXTENSIONS = new Set([".bat", ".cmd"]);
+const WINDOWS_NODE_SCRIPT_EXTENSIONS = new Set([".cjs", ".js", ".mjs"]);
 type CodegraphBootstrapConfig = CodegraphConfig & {
 	readonly trustedCodegraphInstallDir?: string;
 };
@@ -160,7 +161,7 @@ function jsonSaysInitialized(value: unknown): boolean | undefined {
 async function runCodegraphCommand(projectRoot: string, command: string, args: readonly string[], options: { readonly env: Record<string, string>; readonly timeoutMs: number }): Promise<CodegraphCommandResult> {
 	const invocation = resolveCodegraphCommandInvocation(command, args);
 	return new Promise((resolvePromise) => {
-		execFile(invocation.command, [...invocation.args], { cwd: projectRoot, encoding: "utf8", env: { ...process.env, ...options.env }, maxBuffer: 1024 * 1024, timeout: options.timeoutMs, windowsHide: true }, (error, stdout, stderr) => {
+		execFile(invocation.command, [...invocation.args], { cwd: projectRoot, encoding: "utf8", env: buildCodegraphChildEnv({ ambientEnv: processEnv, codegraphEnv: options.env }), maxBuffer: 1024 * 1024, timeout: options.timeoutMs, windowsHide: true }, (error, stdout, stderr) => {
 			if (error === null) {
 				resolvePromise({ exitCode: 0, stderr: toOutputText(stderr), stdout: toOutputText(stdout), timedOut: false });
 				return;
@@ -176,7 +177,9 @@ export function resolveCodegraphCommandInvocation(
 	platform: NodeJS.Platform = process.platform,
 ): { readonly args: readonly string[]; readonly command: string } {
 	if (platform !== "win32") return { args: [...args], command };
-	if (!WINDOWS_CMD_EXTENSIONS.has(extname(command).toLowerCase())) return { args: [...args], command };
+	const extension = extname(command).toLowerCase();
+	if (WINDOWS_NODE_SCRIPT_EXTENSIONS.has(extension)) return { args: [command, ...args], command: processExecPath };
+	if (!WINDOWS_CMD_EXTENSIONS.has(extension)) return { args: [...args], command };
 	return { args: ["/d", "/s", "/c", command, ...args], command: "cmd.exe" };
 }
 

package/packages/omo-codex/plugin/components/codegraph/test/hook.test.ts

@@ -15,6 +15,13 @@ import {
 const pluginRoot = resolve(fileURLToPath(new URL("../../..", import.meta.url)));
 const pluginConfigPath = resolve(pluginRoot, ".codex-plugin/plugin.json");
 
+function expectOmoCodegraphProjectStoreGuidance(context: string): void {
+	expect(context).toContain(".omo");
+	expect(context).toContain("codegraph");
+	expect(context).toContain("projects");
+	expect(context).toContain("project-");
+}
+
 describe("CodeGraph SessionStart hook", () => {
 	it("#given hook session-start cli args #when invoked with empty JSON input #then it emits valid JSON and exits zero", async () => {
 		// given
@@ -30,6 +37,7 @@ describe("CodeGraph SessionStart hook", () => {
 				stdin: Readable.from(["{}"]),
 				stdout: { write: (chunk) => stdout.push(chunk) },
 				spawnWorker: (invocation) => spawned.push(invocation),
+				statusProbe: () => Promise.resolve(false),
 			});
 
 			// then
@@ -67,12 +75,9 @@ describe("CodeGraph SessionStart hook", () => {
 		const parsed = JSON.parse(output);
 
 		// then
-		expect(parsed).toEqual({
-			hookSpecificOutput: {
-				hookEventName: "PostToolUse",
-				additionalContext: expect.stringContaining('"/Users/me/.omo/codegraph/projects/project-'),
-			},
-		});
+		expect(parsed.hookSpecificOutput.hookEventName).toBe("PostToolUse");
+		expect(parsed.hookSpecificOutput.additionalContext).toContain('CodeGraph is not initialized for "/Users/me/project"');
+		expectOmoCodegraphProjectStoreGuidance(parsed.hookSpecificOutput.additionalContext);
 		expect(parsed.hookSpecificOutput.additionalContext).toContain('run `codegraph init` from "/Users/me/project"');
 	});
 
@@ -92,7 +97,7 @@ describe("CodeGraph SessionStart hook", () => {
 
 		// then
 		expect(parsed.hookSpecificOutput.additionalContext).toContain('CodeGraph is not initialized for "/Users/me/project"');
-		expect(parsed.hookSpecificOutput.additionalContext).toContain('"/Users/me/.omo/codegraph/projects/project-');
+		expectOmoCodegraphProjectStoreGuidance(parsed.hookSpecificOutput.additionalContext);
 	});
 
 	it("#given CodeGraph is disabled by Codex SOT config #when SessionStart fires #then it skips without spawning", async () => {
@@ -214,10 +219,11 @@ describe("CodeGraph SessionStart hook", () => {
 			const result = await executeCodegraphSessionStartHook({
 				config: { codegraph: { enabled: true }, sources: [], warnings: [] },
 				cwd: workspace,
-				env: { HOME: "/tmp/home", KEEP: "1" },
+				env: { HOME: "/tmp/home", KEEP: "1", OPENAI_API_KEY: "sk-test-secret" },
 				stdin: Readable.from(["{}"]),
 				stdout: { write: (chunk) => stdout.push(chunk) },
 				spawnWorker: (invocation) => spawned.push(invocation),
+				statusProbe: () => Promise.resolve(false),
 				workerCliPath: "/plugin/components/codegraph/dist/cli.js",
 			});
 
@@ -229,11 +235,12 @@ describe("CodeGraph SessionStart hook", () => {
 					command: process.execPath,
 					env: {
 						HOME: "/tmp/home",
-						KEEP: "1",
 						OMO_CODEGRAPH_SESSION_START_CWD: workspace,
 					},
 				},
 			]);
+			expect(spawned[0]?.env["OPENAI_API_KEY"]).toBeUndefined();
+			expect(spawned[0]?.env["KEEP"]).toBeUndefined();
 			expect(JSON.parse(stdout.join(""))).toEqual({
 				hookSpecificOutput: {
 					additionalContext: "LazyCodex CodeGraph bootstrap scheduled in background",
@@ -245,6 +252,33 @@ describe("CodeGraph SessionStart hook", () => {
 		}
 	});
 
+	it("#given CodeGraph is already initialized #when SessionStart fires #then it stays silent without spawning", async () => {
+		// given
+		const stdout: string[] = [];
+		const spawned: WorkerSpawnInvocation[] = [];
+		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-initialized-workspace-"));
+
+		try {
+			// when
+			const result = await executeCodegraphSessionStartHook({
+				config: { codegraph: { enabled: true }, sources: [], warnings: [] },
+				cwd: workspace,
+				env: { HOME: "/tmp/home", KEEP: "1" },
+				stdin: Readable.from(["{}"]),
+				stdout: { write: (chunk) => stdout.push(chunk) },
+				spawnWorker: (invocation) => spawned.push(invocation),
+				statusProbe: () => Promise.resolve(true),
+			});
+
+			// then
+			expect(result).toEqual({ action: "skipped-initialized", exitCode: 0 });
+			expect(spawned).toEqual([]);
+			expect(stdout.join("")).toBe("");
+		} finally {
+			rmSync(workspace, { recursive: true, force: true });
+		}
+	});
+
 	it("#given malformed hook input with CodeGraph disabled #when SessionStart fires #then it stays silent and exits zero", async () => {
 		// given
 		const stdout: string[] = [];