oh-my-opencode 4.8.1 → 4.9.1

package/packages/omo-codex/plugin/components/rules/test/codex-hook-post-compact-budget.test.ts

@@ -25,7 +25,7 @@ afterEach(() => {
 });
 
 describe("codex rules post-compaction context budget", () => {
-	it("#given oversized project rules already injected #when static recovery runs after compaction #then it emits no duplicate static injection", async () => {
+	it("#given oversized project rules already injected #when static recovery runs after compaction #then it emits a mandatory read directive instead of rule bodies", async () => {
 		// given
 		const { root, pluginData } = makeOversizedProject();
 		const firstOutput = await runSessionStartHook(sessionStartInput(root), {
@@ -50,7 +50,12 @@ describe("codex rules post-compaction context budget", () => {
 		expect(firstContext).toContain("Project rule");
 		expect(firstContext).toContain("[Truncated. Full:");
 		expect(firstContext.length).toBeLessThan(31_000);
-		expect(output).toBe("");
+		const recoveryContext = readAdditionalContext(output);
+		expect(recoveryContext).toContain("MUST READ");
+		expect(recoveryContext).toContain("NO EXCUSES");
+		expect(recoveryContext).toContain(path.join(root, "CONTEXT.md"));
+		expect(recoveryContext).not.toContain("Project rule");
+		expect(recoveryContext.length).toBeLessThan(2_000);
 	});
 });
 

package/packages/omo-codex/plugin/components/rules/test/codex-hook-post-compact-context.test.ts

@@ -20,7 +20,7 @@ afterEach(() => {
 });
 
 describe("codex rules compacted context recovery", () => {
-	it("#given compacted session source after PostCompact #when static rules re-inject #then output uses the compact recovery budget", async () => {
+	it("#given compacted session source after PostCompact #when static recovery runs #then output is a mandatory read directive", async () => {
 		// given
 		const { root, pluginData } = makeOversizedProject("compact-source");
 		const transcriptPath = writeCompactedTranscript(root, "summary dropped injected rules");
@@ -37,10 +37,10 @@ describe("codex rules compacted context recovery", () => {
 
 		// then
 		const postCompactContext = readAdditionalContext(output);
-		expect(postCompactContext.length).toBeLessThan(5_000);
-		expect(postCompactContext).toContain("Instructions from:");
+		expect(postCompactContext.length).toBeLessThan(2_000);
+		expect(postCompactContext).toContain("MUST READ");
 		expect(postCompactContext).toContain("CONTEXT.md");
-		expect(postCompactContext).toContain("Project rule");
+		expect(postCompactContext).not.toContain("Project rule");
 	});
 
 	it("#given compacted context warning and near-full transcript #when compact source starts twice #then handles compacted context warning once", async () => {
@@ -65,7 +65,7 @@ describe("codex rules compacted context recovery", () => {
 		// then
 		const firstContext = readOptionalAdditionalContext(firstOutput);
 		expect(firstContext.length).toBeLessThan(1_000);
-		expect(firstContext).toContain("Instructions from:");
+		expect(firstContext).toContain("MUST READ");
 		expect(firstContext).toContain("CONTEXT.md");
 		expect(secondOutput).toBe("");
 	});
@@ -88,7 +88,7 @@ describe("codex rules compacted context recovery", () => {
 		// then
 		const context = readOptionalAdditionalContext(output);
 		expect(context.length).toBeLessThan(1_000);
-		expect(context).toContain("Instructions from:");
+		expect(context).toContain("MUST READ");
 		expect(context).toContain("CONTEXT.md");
 	});
 
@@ -106,7 +106,7 @@ describe("codex rules compacted context recovery", () => {
 		// then
 		const context = readOptionalAdditionalContext(output);
 		expect(context.length).toBeLessThan(1_000);
-		expect(context).toContain("Instructions from:");
+		expect(context).toContain("MUST READ");
 		expect(context).toContain("CONTEXT.md");
 	});
 
@@ -128,7 +128,7 @@ describe("codex rules compacted context recovery", () => {
 		// then
 		const context = readOptionalAdditionalContext(output);
 		expect(context.length).toBeLessThan(1_000);
-		expect(context).toContain("Instructions from:");
+		expect(context).toContain("MUST READ");
 		expect(context).toContain("CONTEXT.md");
 	});
 
@@ -157,7 +157,7 @@ describe("codex rules compacted context recovery", () => {
 		const contexts = outputs.map(readOptionalAdditionalContext);
 		expect(contexts.filter((context) => context.length > 0)).toHaveLength(1);
 		expect(contexts.join("").length).toBeLessThan(1_000);
-		expect(contexts.join("")).toContain("Instructions from:");
+		expect(contexts.join("")).toContain("MUST READ");
 		expect(contexts.join("")).toContain("CONTEXT.md");
 	});
 });

package/packages/omo-codex/plugin/components/rules/test/codex-hook-post-compact-dedup.test.ts

@@ -93,7 +93,7 @@ describe("codex rules PostCompact deduplication", () => {
 		expect(output).toBe("");
 	});
 
-	it("#given startup already injected static context #when UserPromptSubmit runs after PostCompact #then it emits no duplicate static context", async () => {
+	it("#given startup static context dropped by compaction #when UserPromptSubmit runs after PostCompact #then it emits a mandatory read directive without rule bodies", async () => {
 		// given
 		const { root, pluginData } = makeTempProject();
 		await runSessionStartHook(sessionStartInput(root), {
@@ -113,10 +113,13 @@ describe("codex rules PostCompact deduplication", () => {
 		});
 
 		// then
-		expect(output).toBe("");
+		const context = readAdditionalContext(output);
+		expect(context).toContain("MUST READ");
+		expect(context).toContain("CONTEXT.md");
+		expect(context).not.toContain("Instructions from:");
 	});
 
-	it("#given startup already injected static context #when compact SessionStart runs after PostCompact #then it emits no duplicate static context", async () => {
+	it("#given startup static context dropped by compaction #when compact SessionStart runs after PostCompact #then it emits a mandatory read directive without rule bodies", async () => {
 		// given
 		const { root, pluginData } = makeTempProject();
 		await runSessionStartHook(sessionStartInput(root), {
@@ -136,7 +139,10 @@ describe("codex rules PostCompact deduplication", () => {
 		});
 
 		// then
-		expect(output).toBe("");
+		const context = readAdditionalContext(output);
+		expect(context).toContain("MUST READ");
+		expect(context).toContain("CONTEXT.md");
+		expect(context).not.toContain("Instructions from:");
 	});
 });
 

package/packages/omo-codex/plugin/components/rules/test/codex-hook-post-compact-directive.test.ts

@@ -0,0 +1,241 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+	type CodexPostCompactInput,
+	type CodexPostToolUseInput,
+	type CodexSessionStartInput,
+	type CodexUserPromptSubmitInput,
+	runPostCompactHook,
+	runPostToolUseHook,
+	runSessionStartHook,
+	runUserPromptSubmitHook,
+} from "../src/codex-hook.js";
+
+const tempDirectories: string[] = [];
+const PROJECT_ONLY_ENV = {
+	CODEX_RULES_ENABLED_SOURCES: "CONTEXT.md,.omo/rules",
+};
+const SESSION_ID = "session-post-compact-directive";
+
+afterEach(() => {
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+describe("codex rules post-compaction read directive", () => {
+	it("#given injected rules dropped by compaction #when UserPromptSubmit recovers #then it lists rule paths in a mandatory read directive instead of bodies", async () => {
+		// given
+		const { root, pluginData } = makeProject();
+		await runSessionStartHook(sessionStartInput(root), { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV });
+		const dynamicOutput = await runPostToolUseHook(postToolUseInput(root, path.join(root, "src", "app.ts")), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_ONLY_ENV,
+		});
+		const transcriptPath = writeCompactedTranscript(root, "summary that dropped every injected rule");
+		await runPostCompactHook(
+			{ ...postCompactInput(root), transcript_path: transcriptPath },
+			{ pluginDataRoot: pluginData },
+		);
+
+		// when
+		const output = await runUserPromptSubmitHook(userPromptSubmitInput(root, transcriptPath), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_ONLY_ENV,
+		});
+
+		// then
+		expect(dynamicOutput).toContain("TypeScript rule");
+		const context = readAdditionalContext(output);
+		expect(context).toContain("MUST READ");
+		expect(context).toContain("NO EXCUSES");
+		expect(context).toContain("CONTEXT.md");
+		expect(context).toContain(".omo/rules/typescript.md");
+		expect(context).not.toContain("A".repeat(50));
+		expect(context).not.toContain("B".repeat(50));
+		expect(context.length).toBeLessThan(2_000);
+	});
+
+	it("#given recovery directive already emitted #when UserPromptSubmit runs again #then it emits nothing", async () => {
+		// given
+		const { root, pluginData } = makeProject();
+		await runSessionStartHook(sessionStartInput(root), { pluginDataRoot: pluginData, env: PROJECT_ONLY_ENV });
+		const transcriptPath = writeCompactedTranscript(root, "summary that dropped every injected rule");
+		await runPostCompactHook(
+			{ ...postCompactInput(root), transcript_path: transcriptPath },
+			{ pluginDataRoot: pluginData },
+		);
+		await runUserPromptSubmitHook(userPromptSubmitInput(root, transcriptPath), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_ONLY_ENV,
+		});
+
+		// when
+		const secondOutput = await runUserPromptSubmitHook(userPromptSubmitInput(root, transcriptPath), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_ONLY_ENV,
+		});
+
+		// then
+		expect(secondOutput).toBe("");
+	});
+
+	it("#given rules retained in compacted replacement #when UserPromptSubmit recovers #then it emits nothing", async () => {
+		// given
+		const { root, pluginData } = makeProject();
+		const firstOutput = await runSessionStartHook(sessionStartInput(root), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_ONLY_ENV,
+		});
+		const transcriptPath = writeCompactedTranscript(root, readAdditionalContext(firstOutput));
+		await runPostCompactHook(
+			{ ...postCompactInput(root), transcript_path: transcriptPath },
+			{ pluginDataRoot: pluginData },
+		);
+
+		// when
+		const output = await runUserPromptSubmitHook(userPromptSubmitInput(root, transcriptPath), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_ONLY_ENV,
+		});
+
+		// then
+		expect(output).toBe("");
+	});
+
+	it("#given bundled hephaestus rule dropped by compaction #when compact SessionStart recovers #then hephaestus body is re-injected in full alongside the directive", async () => {
+		// given
+		const { root, pluginData } = makeProject();
+		const env = { CODEX_RULES_ENABLED_SOURCES: "CONTEXT.md,plugin-bundled" };
+		await runSessionStartHook(sessionStartInput(root), { pluginDataRoot: pluginData, env });
+		const transcriptPath = writeCompactedTranscript(root, "summary that dropped every injected rule");
+		await runPostCompactHook(
+			{ ...postCompactInput(root), transcript_path: transcriptPath },
+			{ pluginDataRoot: pluginData },
+		);
+
+		// when
+		const output = await runSessionStartHook(compactSessionStartInput(root, transcriptPath), {
+			pluginDataRoot: pluginData,
+			env,
+		});
+
+		// then
+		const context = readAdditionalContext(output);
+		expect(context).toContain("You are Hephaestus");
+		expect(context).not.toContain("[Truncated. Full:");
+		expect(context).toContain("MUST READ");
+		expect(context).toContain("CONTEXT.md");
+	});
+});
+
+function makeProject(): { root: string; pluginData: string } {
+	const root = mkdtempSync(path.join(tmpdir(), "codex-rules-directive-project-"));
+	const pluginData = mkdtempSync(path.join(tmpdir(), "codex-rules-directive-data-"));
+	tempDirectories.push(root, pluginData);
+	writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "fixture" }));
+	writeFileSync(path.join(root, "CONTEXT.md"), `Project rule\n${"A".repeat(8_000)}`);
+	mkdirSync(path.join(root, ".omo", "rules"), { recursive: true });
+	writeFileSync(
+		path.join(root, ".omo", "rules", "typescript.md"),
+		["---", 'globs: "**/*.ts"', "---", "", `TypeScript rule\n${"B".repeat(2_000)}`].join("\n"),
+	);
+	mkdirSync(path.join(root, "src"), { recursive: true });
+	writeFileSync(path.join(root, "src", "app.ts"), "export const app = 1;\n");
+	return { root, pluginData };
+}
+
+function sessionStartInput(root: string): CodexSessionStartInput {
+	return {
+		session_id: SESSION_ID,
+		transcript_path: null,
+		cwd: root,
+		hook_event_name: "SessionStart",
+		model: "gpt-5.5",
+		permission_mode: "default",
+		source: "startup",
+	};
+}
+
+function compactSessionStartInput(root: string, transcriptPath: string): CodexSessionStartInput {
+	return {
+		session_id: SESSION_ID,
+		transcript_path: transcriptPath,
+		cwd: root,
+		hook_event_name: "SessionStart",
+		model: "gpt-5.5",
+		permission_mode: "default",
+		source: "compact",
+	};
+}
+
+function postCompactInput(root: string): CodexPostCompactInput {
+	return {
+		session_id: SESSION_ID,
+		turn_id: "turn-compact",
+		transcript_path: null,
+		cwd: root,
+		hook_event_name: "PostCompact",
+		model: "gpt-5.5",
+		trigger: "auto",
+	};
+}
+
+function userPromptSubmitInput(root: string, transcriptPath: string): CodexUserPromptSubmitInput {
+	return {
+		session_id: SESSION_ID,
+		turn_id: "turn-after-compact",
+		transcript_path: transcriptPath,
+		cwd: root,
+		hook_event_name: "UserPromptSubmit",
+		model: "gpt-5.5",
+		permission_mode: "default",
+		prompt: "continue",
+	};
+}
+
+function postToolUseInput(root: string, filePath: string): CodexPostToolUseInput {
+	return {
+		session_id: SESSION_ID,
+		turn_id: "turn-tool",
+		transcript_path: null,
+		cwd: root,
+		hook_event_name: "PostToolUse",
+		model: "gpt-5.5",
+		permission_mode: "default",
+		tool_name: "apply_patch",
+		tool_input: { path: filePath },
+		tool_response: {},
+		tool_use_id: "tool-use-1",
+	};
+}
+
+function writeCompactedTranscript(root: string, retainedText: string): string {
+	const transcriptPath = path.join(root, "transcript-compacted.jsonl");
+	writeFileSync(
+		transcriptPath,
+		`${JSON.stringify({
+			type: "compacted",
+			payload: {
+				message: "summary",
+				replacement_history: [{ type: "message", role: "user", content: retainedText }],
+			},
+		})}\n`,
+	);
+	return transcriptPath;
+}
+
+function readAdditionalContext(output: string): string {
+	if (output.trim().length === 0) {
+		throw new Error("Expected hook output to include additional context.");
+	}
+	const parsed: unknown = JSON.parse(output);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return "";
+	const hookSpecificOutput = (parsed as Record<string, unknown>)["hookSpecificOutput"];
+	if (typeof hookSpecificOutput !== "object" || hookSpecificOutput === null) return "";
+	const additionalContext = (hookSpecificOutput as Record<string, unknown>)["additionalContext"];
+	return typeof additionalContext === "string" ? additionalContext : "";
+}

package/packages/omo-codex/plugin/components/rules/test/event-budget.test.ts

@@ -0,0 +1,168 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+	type CodexPostToolUseInput,
+	type CodexSessionStartInput,
+	type CodexUserPromptSubmitInput,
+	runPostToolUseHook,
+	runSessionStartHook,
+	runUserPromptSubmitHook,
+} from "../src/codex-hook.js";
+
+const tempDirectories: string[] = [];
+const PROJECT_ONLY_ENV = {
+	CODEX_RULES_ENABLED_SOURCES: "CONTEXT.md,.omo/rules",
+};
+
+afterEach(() => {
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+describe("codex rules per-event injection budgets", () => {
+	it("#given an oversized glob rule #when PostToolUse injects dynamically #then the block is truncated to the dynamic budget", async () => {
+		// given
+		const { root, pluginData } = makeProject({ dynamicRuleChars: 30_000 });
+
+		// when
+		const output = await runPostToolUseHook(postToolUseInput(root, path.join(root, "src", "app.ts")), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_ONLY_ENV,
+		});
+
+		// then
+		const context = readAdditionalContext(output);
+		expect(context).toContain("[Truncated. Full:");
+		expect(context.length).toBeLessThan(11_000);
+	});
+
+	it("#given a mid-sized static rule #when SessionStart injects #then the body is not truncated", async () => {
+		// given
+		const { root, pluginData } = makeProject({ staticRuleChars: 8_000 });
+
+		// when
+		const output = await runSessionStartHook(sessionStartInput(root), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_ONLY_ENV,
+		});
+
+		// then
+		const context = readAdditionalContext(output);
+		expect(context).not.toContain("[Truncated. Full:");
+		expect(context.length).toBeGreaterThan(8_000);
+	});
+
+	it("#given the same mid-sized static rule #when UserPromptSubmit injects on a fresh session #then the body is truncated to the prompt budget", async () => {
+		// given
+		const { root, pluginData } = makeProject({ staticRuleChars: 8_000 });
+
+		// when
+		const output = await runUserPromptSubmitHook(userPromptSubmitInput(root), {
+			pluginDataRoot: pluginData,
+			env: PROJECT_ONLY_ENV,
+		});
+
+		// then
+		const context = readAdditionalContext(output);
+		expect(context).toContain("[Truncated. Full:");
+		expect(context.length).toBeLessThan(7_000);
+	});
+
+	it("#given dynamic budget env overrides #when PostToolUse injects #then the override budget wins", async () => {
+		// given
+		const { root, pluginData } = makeProject({ dynamicRuleChars: 30_000 });
+
+		// when
+		const output = await runPostToolUseHook(postToolUseInput(root, path.join(root, "src", "app.ts")), {
+			pluginDataRoot: pluginData,
+			env: {
+				...PROJECT_ONLY_ENV,
+				CODEX_RULES_DYNAMIC_MAX_RULE_CHARS: "1000",
+				CODEX_RULES_DYNAMIC_MAX_RESULT_CHARS: "1500",
+			},
+		});
+
+		// then
+		const context = readAdditionalContext(output);
+		expect(context).toContain("[Truncated. Full:");
+		expect(context.length).toBeLessThan(2_000);
+	});
+});
+
+function makeProject(sizes: { staticRuleChars?: number; dynamicRuleChars?: number }): {
+	root: string;
+	pluginData: string;
+} {
+	const root = mkdtempSync(path.join(tmpdir(), "codex-rules-event-budget-project-"));
+	const pluginData = mkdtempSync(path.join(tmpdir(), "codex-rules-event-budget-data-"));
+	tempDirectories.push(root, pluginData);
+	writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "fixture" }));
+	writeFileSync(path.join(root, "CONTEXT.md"), `Project rule\n${"A".repeat(sizes.staticRuleChars ?? 100)}`);
+	mkdirSync(path.join(root, ".omo", "rules"), { recursive: true });
+	writeFileSync(
+		path.join(root, ".omo", "rules", "typescript.md"),
+		["---", 'globs: "**/*.ts"', "---", "", `TypeScript rule\n${"B".repeat(sizes.dynamicRuleChars ?? 100)}`].join(
+			"\n",
+		),
+	);
+	mkdirSync(path.join(root, "src"), { recursive: true });
+	writeFileSync(path.join(root, "src", "app.ts"), "export const app = 1;\n");
+	return { root, pluginData };
+}
+
+function sessionStartInput(root: string): CodexSessionStartInput {
+	return {
+		session_id: `session-budget-${path.basename(root)}`,
+		transcript_path: null,
+		cwd: root,
+		hook_event_name: "SessionStart",
+		model: "gpt-5.5",
+		permission_mode: "default",
+		source: "startup",
+	};
+}
+
+function userPromptSubmitInput(root: string): CodexUserPromptSubmitInput {
+	return {
+		session_id: `session-budget-${path.basename(root)}`,
+		turn_id: "turn-1",
+		transcript_path: null,
+		cwd: root,
+		hook_event_name: "UserPromptSubmit",
+		model: "gpt-5.5",
+		permission_mode: "default",
+		prompt: "continue",
+	};
+}
+
+function postToolUseInput(root: string, filePath: string): CodexPostToolUseInput {
+	return {
+		session_id: `session-budget-${path.basename(root)}`,
+		turn_id: "turn-tool",
+		transcript_path: null,
+		cwd: root,
+		hook_event_name: "PostToolUse",
+		model: "gpt-5.5",
+		permission_mode: "default",
+		tool_name: "apply_patch",
+		tool_input: { path: filePath },
+		tool_response: {},
+		tool_use_id: "tool-use-1",
+	};
+}
+
+function readAdditionalContext(output: string): string {
+	if (output.trim().length === 0) {
+		throw new Error("Expected hook output to include additional context.");
+	}
+	const parsed: unknown = JSON.parse(output);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return "";
+	const hookSpecificOutput = (parsed as Record<string, unknown>)["hookSpecificOutput"];
+	if (typeof hookSpecificOutput !== "object" || hookSpecificOutput === null) return "";
+	const additionalContext = (hookSpecificOutput as Record<string, unknown>)["additionalContext"];
+	return typeof additionalContext === "string" ? additionalContext : "";
+}

package/packages/omo-codex/plugin/components/rules/test/post-compact-budget.test.ts

@@ -14,6 +14,10 @@ const CONFIG: PiRulesConfig = {
 	maxResultChars: 50_000,
 	postCompactMaxRuleChars: 12_000,
 	postCompactMaxResultChars: 20_000,
+	dynamicMaxRuleChars: 4_000,
+	dynamicMaxResultChars: 10_000,
+	promptMaxRuleChars: 6_000,
+	promptMaxResultChars: 16_000,
 	enabledSources: "auto",
 };
 

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

@@ -1,8 +1,8 @@
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { describe, expect, it } from "vitest";
+import { afterAll, describe, expect, it } from "vitest";
 
 import { runSessionStartHook, runUserPromptSubmitHook } from "../src/codex-hook.js";
 import { formatAdditionalContextOutput } from "../src/hook-output.js";
@@ -45,13 +45,29 @@ function parseHookOutput(value: unknown): HookOutput {
 	};
 }
 
+const fixtureRoot = mkdtempSync(join(tmpdir(), "codex-sparkshell-omo-bin-"));
+const omoOnPathDir = join(fixtureRoot, "path-bin");
+const emptyHomeDir = join(fixtureRoot, "empty-home");
+const localBinHomeDir = join(fixtureRoot, "local-bin-home");
+mkdirSync(omoOnPathDir, { recursive: true });
+mkdirSync(emptyHomeDir, { recursive: true });
+mkdirSync(join(localBinHomeDir, ".local", "bin"), { recursive: true });
+writeFileSync(join(omoOnPathDir, "omo"), "#!/bin/sh\n");
+writeFileSync(join(localBinHomeDir, ".local", "bin", "omo"), "#!/bin/sh\n");
+
 describe("Codex Sparkshell awareness", () => {
-	it("#given active Codex app server env #when SessionStart runs #then emits Sparkshell guidance", async () => {
+	afterAll(() => {
+		rmSync(fixtureRoot, { recursive: true, force: true });
+	});
+
+	it("#given active Codex app server env with omo on PATH #when SessionStart runs #then emits Sparkshell guidance", async () => {
 		// given
 		const env = {
 			CODEX_INTERNAL_ORIGINATOR_OVERRIDE: "Codex Desktop",
 			CODEX_SHELL: "1",
 			CODEX_RULES_ENABLED_SOURCES: ".omo/rules",
+			PATH: omoOnPathDir,
+			HOME: emptyHomeDir,
 		};
 
 		// when
@@ -70,6 +86,11 @@ 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)).not.toContain("[REDACTED]");
 	});
 
 	it("#given inactive env #when SessionStart runs #then emits no Sparkshell guidance", async () => {
@@ -102,6 +123,8 @@ describe("Codex Sparkshell awareness", () => {
 			OMO_SPARKSHELL_APP_SERVER_SOCKET: "/tmp/app-server-control.sock",
 			CODEX_THREAD_ID: "thread-sparkshell-cli",
 			CODEX_RULES_ENABLED_SOURCES: ".omo/rules",
+			PATH: omoOnPathDir,
+			HOME: emptyHomeDir,
 		};
 
 		// when
@@ -122,6 +145,64 @@ describe("Codex Sparkshell awareness", () => {
 		expect(parseAdditionalContext(output)).toContain("omo sparkshell <command>");
 	});
 
+	it("#given active Codex app env without a resolvable omo command #when SessionStart runs #then emits no Sparkshell guidance", async () => {
+		// given
+		const env = {
+			CODEX_INTERNAL_ORIGINATOR_OVERRIDE: "Codex Desktop",
+			CODEX_SHELL: "1",
+			CODEX_RULES_ENABLED_SOURCES: ".omo/rules",
+			PATH: join(fixtureRoot, "missing-path-entry"),
+			HOME: emptyHomeDir,
+		};
+
+		// when
+		const output = await runSessionStartHook(
+			{
+				session_id: "session-sparkshell-unresolvable",
+				transcript_path: null,
+				cwd: process.cwd(),
+				hook_event_name: "SessionStart",
+				model: "gpt-5.5",
+				permission_mode: "default",
+				source: "startup",
+			},
+			{ env },
+		);
+
+		// then
+		expect(output).toBe("");
+	});
+
+	it("#given omo only under HOME/.local/bin #when SessionStart runs #then emits guidance with the absolute omo path", async () => {
+		// given
+		const env = {
+			CODEX_INTERNAL_ORIGINATOR_OVERRIDE: "Codex Desktop",
+			CODEX_SHELL: "1",
+			CODEX_RULES_ENABLED_SOURCES: ".omo/rules",
+			PATH: join(fixtureRoot, "missing-path-entry"),
+			HOME: localBinHomeDir,
+		};
+
+		// when
+		const output = await runSessionStartHook(
+			{
+				session_id: "session-sparkshell-local-bin",
+				transcript_path: null,
+				cwd: process.cwd(),
+				hook_event_name: "SessionStart",
+				model: "gpt-5.5",
+				permission_mode: "default",
+				source: "startup",
+			},
+			{ env },
+		);
+
+		// then
+		const context = parseAdditionalContext(output);
+		expect(context).toContain(`${join(localBinHomeDir, ".local", "bin", "omo")} sparkshell <command>`);
+		expect(context).not.toContain("`omo sparkshell <command>`");
+	});
+
 	it("#given explicit force-on env #when SessionStart runs #then emits Sparkshell guidance", async () => {
 		// given
 		const env = {
@@ -181,6 +262,8 @@ describe("Codex Sparkshell awareness", () => {
 			CODEX_INTERNAL_ORIGINATOR_OVERRIDE: "Codex Desktop",
 			CODEX_SHELL: "1",
 			CODEX_RULES_ENABLED_SOURCES: ".omo/rules",
+			PATH: omoOnPathDir,
+			HOME: emptyHomeDir,
 		};
 		try {
 			const firstOutput = await runSessionStartHook(