oh-my-opencode 4.12.1 → 4.13.0

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

@@ -10,32 +10,6 @@ import { resolveServeProcessInvocation, runCodegraphServe } from "../src/serve.t
 const componentRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
 describe("runCodegraphServe", () => {
-	it("#given CodeGraph is unresolved #when serving MCP #then exits non-zero with a one-line skip hint", async () => {
-		// given
-		const stderr: string[] = [];
-		const spawned: string[] = [];
-
-		// when
-		const exitCode = await runCodegraphServe({
-			config: { codegraph: { auto_provision: false, enabled: true }, sources: [], warnings: [] },
-			env: { PATH: "/bin" },
-			buildEnv: () => ({}),
-			resolve: () => ({ argsPrefix: [], command: "codegraph", exists: false, source: "path" }),
-			runProcess: (command: string) => {
-				spawned.push(command);
-				return Promise.resolve(0);
-			},
-			stderr: { write: (chunk: string) => stderr.push(chunk) },
-		});
-
-		// then
-		expect(exitCode).toBe(1);
-		expect(spawned).toEqual([]);
-		expect(stderr).toEqual([
-			"CodeGraph MCP skipped: codegraph binary not found. Install CodeGraph or set OMO_CODEGRAPH_BIN.\n",
-		]);
-	});
-
 	it("#given CodeGraph resolves #when serving MCP #then execs codegraph serve --mcp with inherited stdio and telemetry disabled", async () => {
 		// given
 		const calls: Array<{
@@ -87,32 +61,6 @@ describe("runCodegraphServe", () => {
 		]);
 	});
 
-	it("#given an unsupported local Node #when serving MCP #then skips fast without spawning codegraph", async () => {
-		// given
-		const stderr: string[] = [];
-		const spawned: string[] = [];
-
-		// when
-		const exitCode = await runCodegraphServe({
-			env: {},
-			nodeVersion: "26.3.0",
-			buildEnv: () => ({}),
-			resolve: () => ({ argsPrefix: [], command: "codegraph", exists: true, source: "path" }),
-			runProcess: (command: string) => {
-				spawned.push(command);
-				return Promise.resolve(0);
-			},
-			stderr: { write: (chunk: string) => stderr.push(chunk) },
-		});
-
-		// then
-		expect(exitCode).toBe(1);
-		expect(spawned).toEqual([]);
-		expect(stderr).toHaveLength(1);
-		expect(stderr[0]).toContain("CodeGraph MCP skipped");
-		expect(stderr[0]).toContain("CODEGRAPH_ALLOW_UNSAFE_NODE");
-	});
-
 	it("#given an unsupported local Node but the unsafe override is set #when serving MCP #then it still spawns codegraph", async () => {
 		// given
 		const spawned: string[] = [];
@@ -182,66 +130,6 @@ describe("runCodegraphServe", () => {
 		expect(spawned).toEqual([{ args: ["serve", "--mcp"], command: commandPath }]);
 	});
 
-	it("#given OMO_CODEGRAPH_BIN points at a missing path #when serving MCP #then exits before spawn", async () => {
-		// given
-		const stderr: string[] = [];
-		const spawned: string[] = [];
-
-		// when
-		const exitCode = await runCodegraphServe({
-			buildEnv: () => ({}),
-			commandExists: () => false,
-			resolve: () => ({ argsPrefix: [], command: "/nonexistent", exists: true, source: "env" }),
-			runProcess: (command: string) => {
-				spawned.push(command);
-				return Promise.resolve(0);
-			},
-			stderr: { write: (chunk: string) => stderr.push(chunk) },
-		});
-
-		// then
-		expect(exitCode).toBe(1);
-		expect(spawned).toEqual([]);
-		expect(stderr).toEqual([
-			"CodeGraph MCP skipped: codegraph binary not found. Install CodeGraph or set OMO_CODEGRAPH_BIN.\n",
-		]);
-	});
-
-	it("#given Codex SOT disables CodeGraph #when serving MCP #then exits non-zero with a disabled hint", async () => {
-		// given
-		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-serve-disabled-home-"));
-		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-serve-disabled-workspace-"));
-		const stderr: string[] = [];
-		const spawned: string[] = [];
-		try {
-			mkdirSync(join(homeDir, ".omo"), { recursive: true });
-			mkdirSync(join(workspace, ".omo"), { recursive: true });
-			writeFileSync(join(homeDir, ".omo", "config.jsonc"), '{ "codegraph": { "enabled": true } }\n');
-			writeFileSync(join(workspace, ".omo", "config.jsonc"), '{ "[codex]": { "codegraph": { "enabled": false } } }\n');
-
-			// when
-			const exitCode = await runCodegraphServe({
-				cwd: workspace,
-				env: { HOME: homeDir },
-				runProcess: (command: string) => {
-					spawned.push(command);
-					return Promise.resolve(0);
-				},
-				stderr: { write: (chunk: string) => stderr.push(chunk) },
-			});
-
-			// then
-			expect(exitCode).toBe(1);
-			expect(spawned).toEqual([]);
-			expect(stderr).toEqual([
-				"CodeGraph MCP skipped: disabled by OMO SOT config. Set [codex].codegraph.enabled=true to enable it.\n",
-			]);
-		} finally {
-			rmSync(homeDir, { recursive: true, force: true });
-			rmSync(workspace, { recursive: true, force: true });
-		}
-	});
-
 	it("#given Windows Codex SOT install_dir has codegraph.cmd #when serving MCP #then it resolves there and exports CODEGRAPH_INSTALL_DIR", async () => {
 		await withProcessPlatform("win32", async () => {
 			// given
@@ -260,7 +148,7 @@ describe("runCodegraphServe", () => {
 
 				// when
 				const exitCode = await runCodegraphServe({
-					config: { codegraph: { enabled: true, install_dir: installDir }, sources: [], warnings: [] },
+					config: { codegraph: { enabled: true, install_dir: installDir }, sources: [], trustedCodegraphInstallDir: installDir, warnings: [] },
 					env: { HOME: "/tmp/home" },
 					nodeVersion: "22.14.0",
 					homeDir: "/tmp/home",

package/packages/omo-codex/plugin/components/codegraph/test/session-start-node-support.test.ts

@@ -52,6 +52,7 @@ describe("CodeGraph SessionStart worker Node support", () => {
 		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-node-provision-home-"));
 		const binPath = join(homeDir, ".omo", "codegraph", "bin", "codegraph");
 		const calls: Array<{ readonly args: readonly string[]; readonly command: string }> = [];
+		const provisionCalls: Array<{ readonly installDir?: string; readonly lockDir: string; readonly version: "1.0.1" }> = [];
 		const outcomes: unknown[] = [];
 
 		try {
@@ -63,7 +64,10 @@ describe("CodeGraph SessionStart worker Node support", () => {
 				logOutcome: (outcome) => outcomes.push(outcome),
 				deps: {
 					ensureGitignored: () => true,
-					ensureProvisioned: () => Promise.resolve({ binPath, provisioned: true }),
+					ensureProvisioned: (options) => {
+						provisionCalls.push(options);
+						return Promise.resolve({ binPath, provisioned: true });
+					},
 					prepareWorkspace: () => ({
 						dataDir: join(homeDir, ".omo/codegraph/projects/test"),
 						dataRoot: join(homeDir, ".omo/codegraph"),
@@ -85,6 +89,9 @@ describe("CodeGraph SessionStart worker Node support", () => {
 				{ args: ["status", "--json"], command: binPath },
 				{ args: ["init"], command: binPath },
 			]);
+			expect(provisionCalls).toEqual([
+				{ installDir: join(homeDir, ".omo", "codegraph"), lockDir: join(homeDir, ".omo", "codegraph", ".locks"), version: "1.0.1" },
+			]);
 			expect(outcomes).toEqual([{ action: "initialized", exitCode: 0, projectRoot: workspace, source: "provisioned", timedOut: false }]);
 		} finally {
 			rmSync(workspace, { recursive: true, force: true });

package/packages/omo-codex/plugin/components/codegraph/test/session-start-trust-boundary.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runCodegraphSessionStartWorker } from "../src/hook.ts";
+
+describe("CodeGraph SessionStart trust boundary", () => {
+	it("#given project config sets install_dir #when worker provisions CodeGraph #then it uses the trusted home install root", async () => {
+		// given
+		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-untrusted-project-"));
+		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-untrusted-project-home-"));
+		const attackerInstallDir = join(workspace, "attacker-install");
+		const trustedInstallDir = join(homeDir, ".omo", "codegraph");
+		const calls: Array<{ readonly env: Record<string, string>; readonly installDir?: string; readonly lockDir?: string }> = [];
+		try {
+			mkdirSync(join(workspace, ".omo"), { recursive: true });
+			writeFileSync(join(workspace, ".omo", "config.jsonc"), JSON.stringify({ codegraph: { enabled: true, install_dir: attackerInstallDir } }));
+
+			// when
+			const result = await runCodegraphSessionStartWorker({
+				cwd: workspace,
+				env: { HOME: homeDir },
+				nodeVersion: "22.14.0",
+				deps: {
+					ensureGitignored: () => true,
+					ensureProvisioned: (options) => {
+						calls.push({
+							env: {},
+							...(options.installDir === undefined ? {} : { installDir: options.installDir }),
+							...(options.lockDir === undefined ? {} : { lockDir: options.lockDir }),
+						});
+						return Promise.resolve({ binPath: join(trustedInstallDir, "bin", "codegraph"), provisioned: true });
+					},
+					prepareWorkspace: () => ({
+						dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+						dataRoot: join(homeDir, ".omo/codegraph"),
+						linked: true,
+						mode: "global-linked",
+						projectLink: join(workspace, ".codegraph"),
+					}),
+					resolveCommand: (options) => {
+						expect(options?.provisioned?.()).toBe(null);
+						return { argsPrefix: [], command: "missing-codegraph", exists: false, source: "path" };
+					},
+					runCommand: (_projectRoot, _command, _args, options) => {
+						calls.push({ env: options.env });
+						return Promise.resolve({ exitCode: 0, stdout: calls.length === 2 ? '{"initialized":false}' : "", timedOut: false });
+					},
+				},
+			});
+
+			// then
+			expect(result).toEqual({ action: "initialized" });
+			expect(calls[0]).toEqual({ env: {}, installDir: trustedInstallDir, lockDir: join(trustedInstallDir, ".locks") });
+			expect(calls[1]?.env["CODEGRAPH_INSTALL_DIR"]).toBe(trustedInstallDir);
+			expect(calls[1]?.env["CODEGRAPH_INSTALL_DIR"]).not.toBe(attackerInstallDir);
+		} finally {
+			rmSync(workspace, { recursive: true, force: true });
+			rmSync(homeDir, { recursive: true, force: true });
+		}
+	});
+});

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

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runCodegraphSessionStartWorker } from "../src/hook.ts";
+
+describe("CodeGraph SessionStart worker availability", () => {
+	it("#given CodeGraph cannot be resolved or provisioned #when worker runs #then it logs a graceful skip", async () => {
+		// given
+		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-"));
+		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-home-"));
+		const outcomes: unknown[] = [];
+		const calls: string[] = [];
+
+		try {
+			// when
+			const result = await runCodegraphSessionStartWorker({
+				cwd: workspace,
+				env: { HOME: homeDir },
+				nodeVersion: "22.14.0",
+				logOutcome: (outcome) => outcomes.push(outcome),
+				deps: {
+					ensureGitignored: () => {
+						calls.push("ensureGitignored");
+						return true;
+					},
+					ensureProvisioned: () => Promise.resolve({ error: "offline", provisioned: false }),
+					prepareWorkspace: () => {
+						calls.push("prepareWorkspace");
+						return {
+							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+							dataRoot: join(homeDir, ".omo/codegraph"),
+							linked: true,
+							mode: "global-linked",
+							projectLink: join(workspace, ".codegraph"),
+						};
+					},
+					resolveCommand: () => ({ argsPrefix: [], command: "codegraph", exists: false, source: "path" }),
+					runCommand: () => {
+						calls.push("runCommand");
+						return Promise.resolve({ exitCode: 0, stdout: "", timedOut: false });
+					},
+				},
+			});
+
+			// then
+			expect(result).toEqual({ action: "skipped-unavailable" });
+			expect(calls).toEqual([]);
+			expect(outcomes).toEqual([
+				{
+					action: "skipped-unavailable",
+					error: "offline",
+					projectRoot: workspace,
+					source: "path",
+				},
+			]);
+		} finally {
+			rmSync(workspace, { recursive: true, force: true });
+			rmSync(homeDir, { recursive: true, force: true });
+		}
+	});
+
+	it("#given CodeGraph is unavailable and auto provisioning is disabled #when worker runs #then it leaves the project untouched", async () => {
+		// given
+		const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-unavailable-"));
+		const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-unavailable-home-"));
+		const outcomes: unknown[] = [];
+
+		try {
+			// when
+			const result = await runCodegraphSessionStartWorker({
+				config: { codegraph: { auto_provision: false, enabled: true }, sources: [], warnings: [] },
+				nodeVersion: "22.14.0",
+				cwd: workspace,
+				env: { HOME: homeDir },
+				logOutcome: (outcome) => outcomes.push(outcome),
+				deps: {
+					ensureProvisioned: () => {
+						throw new Error("auto provision should not run");
+					},
+					resolveCommand: () => ({ argsPrefix: [], command: "missing-codegraph", exists: false, source: "path" }),
+					runCommand: () => {
+						throw new Error("codegraph command should not run");
+					},
+				},
+			});
+
+			// then
+			expect(result).toEqual({ action: "skipped-unavailable" });
+			expect(existsSync(join(workspace, ".codegraph"))).toBe(false);
+			expect(existsSync(join(workspace, ".git", "info", "exclude"))).toBe(false);
+			expect(outcomes).toEqual([
+				{
+					action: "skipped-unavailable",
+					error: "codegraph binary unavailable and auto_provision is disabled",
+					projectRoot: workspace,
+					source: "path",
+				},
+			]);
+		} finally {
+			rmSync(workspace, { recursive: true, force: true });
+			rmSync(homeDir, { recursive: true, force: true });
+		}
+	});
+});

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

@@ -0,0 +1,150 @@
+import { describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveCodegraphCommandInvocation, runCodegraphSessionStartWorker } from "../src/hook.ts";
+
+describe("CodeGraph SessionStart worker flow", () => {
+	it("#given Windows install_dir has codegraph.cmd #when worker resolves provisioned CodeGraph #then it uses the cmd shim", async () => {
+		await withProcessPlatform("win32", async () => {
+			// given
+			const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-"));
+			const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-home-"));
+			const installDir = mkdtempSync(join(tmpdir(), "omo-codegraph-worker-win32-install-"));
+			const binPath = join(installDir, "bin", "codegraph.cmd");
+			const calls: { readonly args: readonly string[]; readonly command: string; readonly env: Record<string, string> }[] = [];
+			const outcomes: unknown[] = [];
+			try {
+				mkdirSync(join(installDir, "bin"), { recursive: true });
+				writeFileSync(binPath, "");
+
+				// when
+				const result = await runCodegraphSessionStartWorker({
+					config: { codegraph: { enabled: true, install_dir: installDir }, sources: [], trustedCodegraphInstallDir: installDir, warnings: [] },
+					nodeVersion: "22.14.0",
+					cwd: workspace,
+					env: { HOME: homeDir },
+					logOutcome: (outcome) => outcomes.push(outcome),
+					deps: {
+						ensureGitignored: () => true,
+						ensureProvisioned: () => {
+							throw new Error("provisioning should not run when install_dir binary exists");
+						},
+						prepareWorkspace: () => ({
+							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+							dataRoot: join(homeDir, ".omo/codegraph"),
+							linked: true,
+							mode: "global-linked",
+							projectLink: join(workspace, ".codegraph"),
+						}),
+						resolveCommand: (options) => {
+							const provisioned = options?.provisioned?.() ?? null;
+							return { argsPrefix: [], command: provisioned ?? "missing-codegraph", exists: provisioned !== null, source: provisioned === null ? "path" : "provisioned" };
+						},
+						runCommand: (_projectRoot, command, args, options) => {
+							calls.push({ args, command, env: options.env });
+							return Promise.resolve({ exitCode: 0, stdout: calls.length === 1 ? '{"initialized":false}' : "", timedOut: false });
+						},
+					},
+				});
+
+				// then
+				expect(result).toEqual({ action: "initialized" });
+				expect(calls.map((call) => ({ args: [...call.args], command: call.command }))).toEqual([
+					{ args: ["status", "--json"], command: binPath },
+					{ args: ["init"], command: binPath },
+				]);
+				expect(calls[0]?.env["CODEGRAPH_INSTALL_DIR"]).toBe(installDir);
+				expect(outcomes).toEqual([{ action: "initialized", exitCode: 0, projectRoot: workspace, source: "provisioned", timedOut: false }]);
+			} finally {
+				rmSync(workspace, { recursive: true, force: true });
+				rmSync(homeDir, { recursive: true, force: true });
+				rmSync(installDir, { recursive: true, force: true });
+			}
+		});
+	});
+
+	it("#given Windows codegraph.cmd #when default worker runner builds invocation #then it runs through cmd.exe", () => {
+		// given
+		const command = "C:\\Users\\test\\.omo\\codegraph\\bin\\codegraph.cmd";
+
+		// when
+		const invocation = resolveCodegraphCommandInvocation(command, ["status", "--json"], "win32");
+
+		// then
+		expect(invocation).toEqual({
+			args: ["/d", "/s", "/c", command, "status", "--json"],
+			command: "cmd.exe",
+		});
+	});
+
+	it("#given non-Windows codegraph command #when default worker runner builds invocation #then it executes directly", () => {
+		// given
+		const command = "/home/test/.omo/codegraph/bin/codegraph";
+
+		// when
+		const invocation = resolveCodegraphCommandInvocation(command, ["sync"], "linux");
+
+		// then
+		expect(invocation).toEqual({ args: ["sync"], command });
+	});
+
+	it("#given resolved CodeGraph status #when worker runs #then it runs status before init or sync", async () => {
+		for (const scenario of [
+			{ action: "initialized", args: [["status", "--json"], ["init"]], stdout: '{"initialized":false}' },
+			{ action: "synced", args: [["status", "--json"], ["sync"]], stdout: '{"initialized":true}' },
+		] as const) {
+			// given
+			const workspace = mkdtempSync(join(tmpdir(), "omo-codegraph-status-"));
+			const homeDir = mkdtempSync(join(tmpdir(), "omo-codegraph-status-home-"));
+			const calls: { readonly args: readonly string[]; readonly command: string; readonly env: Record<string, string> }[] = [];
+			const outcomes: unknown[] = [];
+			try {
+				// when
+				const result = await runCodegraphSessionStartWorker({
+					config: { codegraph: { enabled: true, install_dir: "/tmp/codegraph-install" }, sources: [], trustedCodegraphInstallDir: "/tmp/codegraph-install", warnings: [] },
+					nodeVersion: "22.14.0",
+					cwd: workspace,
+					env: { HOME: homeDir },
+					logOutcome: (outcome) => outcomes.push(outcome),
+					deps: {
+						ensureGitignored: () => true,
+						ensureProvisioned: () => Promise.resolve({ binPath: "/tmp/codegraph", provisioned: true }),
+						prepareWorkspace: () => ({
+							dataDir: join(homeDir, ".omo/codegraph/projects/test"),
+							dataRoot: join(homeDir, ".omo/codegraph"),
+							linked: true,
+							mode: "global-linked",
+							projectLink: join(workspace, ".codegraph"),
+						}),
+						resolveCommand: () => ({ argsPrefix: [], command: "/tmp/codegraph", exists: true, source: "path" }),
+						runCommand: (_projectRoot, command, args, options) => {
+							calls.push({ args, command, env: options.env });
+							return Promise.resolve({ exitCode: 0, stdout: calls.length === 1 ? scenario.stdout : "", timedOut: false });
+						},
+					},
+				});
+
+				// then
+				expect(result).toEqual({ action: scenario.action });
+				expect(calls.map((call) => [...call.args])).toEqual(scenario.args.map((args) => [...args]));
+				expect(calls[0]?.env["CODEGRAPH_INSTALL_DIR"]).toBe("/tmp/codegraph-install");
+				expect(outcomes).toEqual([{ action: scenario.action, exitCode: 0, projectRoot: workspace, source: "path", timedOut: false }]);
+			} finally {
+				rmSync(workspace, { recursive: true, force: true });
+				rmSync(homeDir, { recursive: true, force: true });
+			}
+		}
+	});
+});
+
+async function withProcessPlatform(platform: NodeJS.Platform, run: () => Promise<void>): Promise<void> {
+	const descriptor = Object.getOwnPropertyDescriptor(process, "platform");
+	Object.defineProperty(process, "platform", { configurable: true, enumerable: true, value: platform });
+	try {
+		await run();
+	} finally {
+		if (descriptor !== undefined) Object.defineProperty(process, "platform", descriptor);
+	}
+}

package/packages/omo-codex/plugin/components/comment-checker/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-comment-checker",
-	"version": "4.12.1",
+	"version": "4.13.0",
 	"description": "Codex plugin that runs comment-checker after edit-like PostToolUse hooks.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/git-bash/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sisyphuslabs/codex-git-bash-hook",
-	"version": "4.12.1",
+	"version": "4.13.0",
 	"description": "Codex hook component that reminds Windows sessions to prefer the OMO git_bash MCP.",
 	"type": "module",
 	"private": true,

package/packages/omo-codex/plugin/components/lazycodex-executor-verify/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-lazycodex-executor-verify",
-	"version": "4.12.1",
+	"version": "4.13.0",
 	"description": "Codex SubagentStop evidence verifier for LazyCodex executor completions.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

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

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-lsp",
-	"version": "4.12.1",
+	"version": "4.13.0",
 	"description": "Codex plugin that exposes Language Server Protocol tools and post-edit diagnostics.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

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

@@ -4032,9 +4032,9 @@ function getSparkShellRuntimeAwareness(env = process.env, deps = {}) {
   return [
     SPARKSHELL_AWARENESS_MARKER,
     "",
-    `- Prefer \`${command} sparkshell <command>\` for repo inspection, CLI smoke tests, git/history checks, and bounded verification before falling back to raw shell commands.`,
-    `- Use \`${command} sparkshell --shell '<command>'\` only when shell metacharacters are required.`,
-    `- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` to inspect an existing tmux pane. Tail lines must stay between 100 and 1000.`,
+    `- Use \`${command} sparkshell <command>\` first for repo inspection, CLI smoke tests, git/history checks, and bounded command output. Raw \`rg\`/\`grep\`/\`cat\`/\`git\` are fallbacks when Sparkshell is unavailable or too narrow for the task.`,
+    `- Use \`${command} sparkshell --shell '<command>'\` only for shell metacharacters or pipelines.`,
+    `- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` only to inspect an existing pane, never to launch ordinary commands. Tail lines must stay between 100 and 1000.`,
     "- When no native sidecar or appserver is available, Sparkshell silently falls back to raw command execution. `OMO_SPARKSHELL_BIN` selects a native sidecar path.",
     "- When `CODEX_THREAD_ID` identifies a Codex session, Sparkshell feeds recent session context (first/latest user request + last 5 conversation messages) into oversized-output condensation for relevance ranking, but never appends that context to command output. `OMO_SPARKSHELL_SESSION_CONTEXT=0` disables the lookup.",
     `- Route potentially huge output (full log files, big diffs, \`cat\`/\`grep\` over large artifacts) through \`${command} sparkshell\` instead of reading it raw: oversized output is condensed to a budget while preserving error signatures, repeated patterns, session-goal-relevant lines, and head/tail. Tune with \`--budget <chars>\`; disable with \`OMO_SPARKSHELL_CONDENSE=0\`.`,

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

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-rules",
-	"version": "4.12.1",
+	"version": "4.13.0",
 	"description": "Codex plugin that injects project rule files into model context through lifecycle hooks.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/rules/src/sparkshell-awareness.ts

@@ -81,9 +81,9 @@ export function getSparkShellRuntimeAwareness(env: RuntimeEnv = process.env, dep
 	return [
 		SPARKSHELL_AWARENESS_MARKER,
 		"",
-		`- Prefer \`${command} sparkshell <command>\` for repo inspection, CLI smoke tests, git/history checks, and bounded verification before falling back to raw shell commands.`,
-		`- Use \`${command} sparkshell --shell '<command>'\` only when shell metacharacters are required.`,
-		`- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` to inspect an existing tmux pane. Tail lines must stay between 100 and 1000.`,
+		`- Use \`${command} sparkshell <command>\` first for repo inspection, CLI smoke tests, git/history checks, and bounded command output. Raw \`rg\`/\`grep\`/\`cat\`/\`git\` are fallbacks when Sparkshell is unavailable or too narrow for the task.`,
+		`- Use \`${command} sparkshell --shell '<command>'\` only for shell metacharacters or pipelines.`,
+		`- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` only to inspect an existing pane, never to launch ordinary commands. Tail lines must stay between 100 and 1000.`,
 		"- When no native sidecar or appserver is available, Sparkshell silently falls back to raw command execution. `OMO_SPARKSHELL_BIN` selects a native sidecar path.",
 		"- When `CODEX_THREAD_ID` identifies a Codex session, Sparkshell feeds recent session context (first/latest user request + last 5 conversation messages) into oversized-output condensation for relevance ranking, but never appends that context to command output. `OMO_SPARKSHELL_SESSION_CONTEXT=0` disables the lookup.",
 		`- Route potentially huge output (full log files, big diffs, \`cat\`/\`grep\` over large artifacts) through \`${command} sparkshell\` instead of reading it raw: oversized output is condensed to a budget while preserving error signatures, repeated patterns, session-goal-relevant lines, and head/tail. Tune with \`--budget <chars>\`; disable with \`OMO_SPARKSHELL_CONDENSE=0\`.`,

package/packages/omo-codex/plugin/components/rules/test/sparkshell-awareness.test.ts

@@ -19,6 +19,29 @@ function parseAdditionalContext(output: string): string {
 	return parsed.hookSpecificOutput?.additionalContext ?? "";
 }
 
+function normalizeGuidance(value: string): string {
+	return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function expectSparkshellFirstContract(value: string): void {
+	const guidance = normalizeGuidance(value);
+
+	expect(guidance).toMatch(/`omo sparkshell <command>`[^.]*\bfirst\b/);
+	expect(guidance).toMatch(/\brepo inspection\b/);
+	expect(guidance).toMatch(/\bcli smoke tests\b/);
+	expect(guidance).toMatch(/\bgit\/history checks\b/);
+	expect(guidance).toMatch(/\bbounded command output\b/);
+	expect(guidance).toMatch(/\braw\b[^.]*`rg`\/`grep`\/`cat`\/`git`[^.]*\bfallbacks?\b/);
+	expect(guidance).toMatch(/\bsparkshell is unavailable\b/);
+	expect(guidance).toMatch(/\btoo narrow\b/);
+	expect(guidance).toMatch(/`omo sparkshell --shell '<command>'`[^.]*\bmetacharacters\b[^.]*\bpipelines\b/);
+	expect(guidance).toMatch(
+		/`omo sparkshell --tmux-pane <pane-id> --tail-lines 400`[^.]*\bonly\b[^.]*\binspect\b[^.]*\bexisting pane\b/,
+	);
+	expect(guidance).toMatch(/`omo sparkshell --tmux-pane <pane-id> --tail-lines 400`[^.]*\bnever\b[^.]*\blaunch ordinary commands\b/);
+	expect(guidance).not.toMatch(/\bprefer\b[^.]*\bbefore raw shell commands\b/);
+}
+
 function parseHookOutput(value: unknown): HookOutput {
 	if (typeof value !== "object" || value === null) {
 		return {};
@@ -85,15 +108,16 @@ describe("Codex Sparkshell awareness", () => {
 		);
 
 		// then
-		expect(parseAdditionalContext(output)).toContain("omo sparkshell <command>");
-		expect(parseAdditionalContext(output)).toContain("OMO_SPARKSHELL_SESSION_CONTEXT");
-		expect(parseAdditionalContext(output)).toContain("OMO_SPARKSHELL_CONDENSE");
-		expect(parseAdditionalContext(output)).toContain("OMO_SPARKSHELL_SPARK");
-		expect(parseAdditionalContext(output)).toContain("[sparkshell caption]");
-		expect(parseAdditionalContext(output)).toContain("never appends that context to command output");
-		expect(parseAdditionalContext(output)).toContain("what the full output contained");
-		expect(parseAdditionalContext(output)).not.toContain("[REDACTED]");
-		expect(parseAdditionalContext(output)).not.toContain("appends recent session context");
+		const context = parseAdditionalContext(output);
+		expectSparkshellFirstContract(context);
+		expect(context).toContain("OMO_SPARKSHELL_SESSION_CONTEXT");
+		expect(context).toContain("OMO_SPARKSHELL_CONDENSE");
+		expect(context).toContain("OMO_SPARKSHELL_SPARK");
+		expect(context).toContain("[sparkshell caption]");
+		expect(context).toContain("never appends that context to command output");
+		expect(context).toContain("what the full output contained");
+		expect(context).not.toContain("[REDACTED]");
+		expect(context).not.toContain("appends recent session context");
 	});
 
 	it("#given inactive env #when SessionStart runs #then emits no Sparkshell guidance", async () => {

package/packages/omo-codex/plugin/components/start-work-continuation/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-start-work-continuation",
-	"version": "4.12.1",
+	"version": "4.13.0",
 	"description": "Codex Stop hook continuation injector for omo-codex start-work plans.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

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

@@ -1,6 +1,6 @@
 {
 	"name": "@sisyphuslabs/codex-teammode",
-	"version": "4.12.1",
+	"version": "4.13.0",
 	"description": "Codex team-mode hook component that keeps background thread titles descriptive after create_thread.",
 	"type": "module",
 	"private": true,