feat: v4.0.0 - Model-specific prompt engineering matching Codex CLI

BREAKING CHANGE: Major prompt engineering overhaul

This release brings full parity with Codex CLI's prompt selection:

Model-Specific Prompts:
- gpt-5.1-codex-max* → gpt-5.1-codex-max_prompt.md (117 lines, frontend design)
- gpt-5.1-codex*, codex-* → gpt_5_codex_prompt.md (105 lines, focused coding)
- gpt-5.1* → gpt_5_1_prompt.md (368 lines, full behavioral guidance)

Legacy GPT-5.0 → GPT-5.1 Migration:
- gpt-5-codex → gpt-5.1-codex
- gpt-5 → gpt-5.1
- gpt-5-mini, gpt-5-nano → gpt-5.1
- codex-mini-latest → gpt-5.1-codex-mini

New Features:
- ModelFamily type for prompt selection ("codex-max" | "codex" | "gpt-5.1")
- getModelFamily() function for model family detection
- Lazy instruction loading per model family
- Separate caching per model family
- Model family logged in request logs

Fixes:
- OpenCode prompt cache URL (main → dev branch)
- Multi-model session log detection in test script

Test Coverage:
- 191 unit tests (16 new for model family detection)
- 13 integration tests with family verification

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: numman-ali

AGENTS.md

@@ -4,7 +4,7 @@ This file provides coding guidance for AI agents (including Claude Code, Codex,
 
 ## Overview
 
-This is an **opencode plugin** that enables OAuth authentication with OpenAI's ChatGPT Plus/Pro Codex backend. It allows users to access `gpt-5.1-codex`, `gpt-5.1-codex-max`, `gpt-5.1-codex-mini`, `gpt-5-codex`, `gpt-5-codex-mini`, `gpt-5.1`, and `gpt-5` models through their ChatGPT subscription instead of using OpenAI Platform API credits.
+This is an **opencode plugin** that enables OAuth authentication with OpenAI's ChatGPT Plus/Pro Codex backend. It allows users to access `gpt-5.1-codex`, `gpt-5.1-codex-max`, `gpt-5.1-codex-mini`, and `gpt-5.1` models through their ChatGPT subscription instead of using OpenAI Platform API credits. Legacy GPT-5.0 models are automatically normalized to their GPT-5.1 equivalents.
 
 **Key architecture principle**: 7-step fetch flow that intercepts opencode's OpenAI SDK requests, transforms them for the ChatGPT backend API, and handles OAuth token management.
 
@@ -97,19 +97,28 @@ The main entry point orchestrates a **7-step fetch flow**:
 - Model-specific options override global
 - Plugin defaults: `reasoningEffort: "medium"`, `reasoningSummary: "auto"`, `textVerbosity: "medium"`
 
-**4. Model Normalization**:
+**4. Model Normalization** (GPT-5.0 → GPT-5.1 migration):
 - All `gpt-5.1-codex-max*` variants → `gpt-5.1-codex-max`
 - All `gpt-5.1-codex*` variants → `gpt-5.1-codex`
 - All `gpt-5.1-codex-mini*` variants → `gpt-5.1-codex-mini`
-- All `gpt-5-codex` variants → `gpt-5-codex`
-- All `gpt-5-codex-mini*` or `codex-mini-latest` variants → `codex-mini-latest`
 - All `gpt-5.1` variants → `gpt-5.1`
-- All `gpt-5` variants → `gpt-5`
+- **Legacy mappings** (GPT-5.0 being phased out):
+  - `gpt-5-codex*` variants → `gpt-5.1-codex`
+  - `gpt-5-codex-mini*` or `codex-mini-latest` → `gpt-5.1-codex-mini`
+  - `gpt-5*` variants (including `gpt-5-mini`, `gpt-5-nano`) → `gpt-5.1`
 - `minimal` effort auto-normalized to `low` for Codex families and clamped to `medium` (or `high` when requested) for Codex Mini
 
-**5. Codex Instructions Caching**:
+**5. Model-Specific Prompt Selection**:
+- Different prompts for different model families (matching Codex CLI):
+  - `gpt-5.1-codex-max*` → `gpt-5.1-codex-max_prompt.md` (117 lines, frontend design guidelines)
+  - `gpt-5.1-codex*`, `codex-*` → `gpt_5_codex_prompt.md` (105 lines, coding focus)
+  - `gpt-5.1*` → `gpt_5_1_prompt.md` (368 lines, full behavioral guidance)
+- `getModelFamily()` determines prompt selection based on normalized model
+
+**6. Codex Instructions Caching**:
 - Fetches from latest release tag (not main branch)
-- ETag-based HTTP conditional requests
+- ETag-based HTTP conditional requests per model family
+- Separate cache files per family: `codex-max-instructions.md`, `codex-instructions.md`, `gpt-5.1-instructions.md`
 - Cache invalidation when release tag changes
 - Falls back to bundled version if GitHub unavailable
 
@@ -140,7 +149,7 @@ OAuth implementation follows OpenAI Codex CLI patterns:
 
 ### Testing Strategy
 
-- **123 comprehensive tests** covering all modules
+- **191 comprehensive tests** covering all modules
 - Test files mirror source structure (`test/auth.test.ts` ↔ `lib/auth/auth.ts`)
 - Mock-heavy testing (no actual network calls or file I/O in tests)
 - Focus on edge cases: token expiration, model normalization, input filtering, CODEX_MODE toggling

CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to this project are documented here. Dates use the ISO format (YYYY-MM-DD).
 
+## [4.0.0] - 2025-11-25
+
+**Major release**: Complete prompt engineering overhaul matching official Codex CLI behavior.
+
+### Added
+- **Model-specific system prompts**: Plugin now fetches the correct Codex prompt based on model family, matching Codex CLI's `model_family.rs` logic:
+  - `gpt-5.1-codex-max*` → `gpt-5.1-codex-max_prompt.md` (117 lines, includes frontend design guidelines)
+  - `gpt-5.1-codex*`, `gpt-5.1-codex-mini*` → `gpt_5_codex_prompt.md` (105 lines, focused coding prompt)
+  - `gpt-5.1*` → `gpt_5_1_prompt.md` (368 lines, full behavioral guidance)
+- New `ModelFamily` type (`"codex-max" | "codex" | "gpt-5.1"`) for prompt selection.
+- New `getModelFamily()` function to determine prompt selection based on normalized model name.
+- Model family now logged in request logs for debugging (`modelFamily` field in after-transform logs).
+- 16 new unit tests for model family detection (now **191 total unit tests**).
+- Integration tests now verify correct model family selection (13 integration tests with family verification).
+
+### Changed
+- **Legacy GPT-5.0 models now map to GPT-5.1**: All legacy `gpt-5` model variants automatically normalize to their `gpt-5.1` equivalents as GPT-5.0 is being phased out by OpenAI:
+  - `gpt-5-codex` → `gpt-5.1-codex`
+  - `gpt-5` → `gpt-5.1`
+  - `gpt-5-mini`, `gpt-5-nano` → `gpt-5.1`
+  - `codex-mini-latest` → `gpt-5.1-codex-mini`
+- **Lazy instruction loading**: Instructions are now fetched per-request based on model family (not pre-loaded at initialization).
+- **Separate caching per model family**: Each model family has its own cached prompt file:
+  - `codex-max-instructions.md` + `codex-max-instructions-meta.json`
+  - `codex-instructions.md` + `codex-instructions-meta.json`
+  - `gpt-5.1-instructions.md` + `gpt-5.1-instructions-meta.json`
+
+### Fixed
+- Fixed OpenCode prompt cache URL to fetch from `dev` branch instead of non-existent `main` branch.
+- Fixed model configuration test script to correctly identify model logs in multi-model sessions (opencode uses a small model like `gpt-5-nano` for title generation alongside the user's selected model).
+
+### Technical Details
+This release brings full parity with Codex CLI's prompt engineering:
+- **Codex family** (105 lines): Concise, tool-focused prompt for coding tasks
+- **Codex Max family** (117 lines): Adds frontend design guidelines for UI work
+- **GPT-5.1 general** (368 lines): Comprehensive behavioral guidance, personality, planning
+
 ## [3.3.0] - 2025-11-19
 ### Added
 - GPT 5.1 Codex Max support: normalization, per-model defaults, and new presets (`gpt-5.1-codex-max`, `gpt-5.1-codex-max-xhigh`) with extended reasoning options (including `none`/`xhigh`) while keeping the 272k context / 128k output limits.

README.md

@@ -44,7 +44,7 @@ Follow me on [X @nummanthinks](https://x.com/nummanthinks) for future updates an
 - ✅ **Automatic tool remapping** - Codex tools → opencode tools
 - ✅ **Configurable reasoning** - Control effort, summary verbosity, and text output
 - ✅ **Usage-aware errors** - Shows clear guidance when ChatGPT subscription limits are reached
-- ✅ **Type-safe & tested** - Strict TypeScript with 160+ unit tests + 14 integration tests
+- ✅ **Type-safe & tested** - Strict TypeScript with 191 unit tests + 13 integration tests
 - ✅ **Modular architecture** - Easy to maintain and extend
 
 ## Installation

config/full-opencode.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
-    "opencode-openai-codex-auth"
+    "file:///Users/numman/Repos/opencode-codex-plugin-fresh/dist"
   ],
   "provider": {
     "openai": {
@@ -226,4 +226,4 @@
       }
     }
   }
-}
+}

index.ts

@@ -46,7 +46,6 @@ import {
 	PROVIDER_ID,
 } from "./lib/constants.js";
 import { logRequest } from "./lib/logger.js";
-import { getCodexInstructions } from "./lib/prompts/codex.js";
 import {
 	createCodexHeaders,
 	extractRequestUrl,
@@ -122,9 +121,6 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 				const pluginConfig = loadPluginConfig();
 				const codexMode = getCodexMode(pluginConfig);
 
-				// Fetch Codex system instructions (cached with ETag for efficiency)
-				const CODEX_INSTRUCTIONS = await getCodexInstructions();
-
 				// Return SDK configuration
 				return {
 					apiKey: DUMMY_API_KEY,
@@ -164,11 +160,11 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 						const originalUrl = extractRequestUrl(input);
 						const url = rewriteUrlForCodex(originalUrl);
 
-						// Step 3: Transform request body with Codex instructions
+						// Step 3: Transform request body with model-specific Codex instructions
+						// Instructions are fetched per model family (codex-max, codex, gpt-5.1)
 						const transformation = await transformRequestForCodex(
 							init,
 							url,
-							CODEX_INSTRUCTIONS,
 							userConfig,
 							codexMode,
 						);

lib/prompts/codex.ts

@@ -1,25 +1,69 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import type { GitHubRelease, CacheMetadata } from "../types.js";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CacheMetadata, GitHubRelease } from "../types.js";
 
 // Codex instructions constants
-const GITHUB_API_RELEASES = "https://api.github.com/repos/openai/codex/releases/latest";
+const GITHUB_API_RELEASES =
+	"https://api.github.com/repos/openai/codex/releases/latest";
 const CACHE_DIR = join(homedir(), ".opencode", "cache");
-const CACHE_FILE = join(CACHE_DIR, "codex-instructions.md");
-const CACHE_METADATA_FILE = join(CACHE_DIR, "codex-instructions-meta.json");
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+/**
+ * Model family type for prompt selection
+ * Maps to different system prompts in the Codex CLI
+ */
+export type ModelFamily = "codex-max" | "codex" | "gpt-5.1";
+
+/**
+ * Prompt file mapping for each model family
+ * Based on codex-rs/core/src/model_family.rs logic
+ */
+const PROMPT_FILES: Record<ModelFamily, string> = {
+	"codex-max": "gpt-5.1-codex-max_prompt.md",
+	codex: "gpt_5_codex_prompt.md",
+	"gpt-5.1": "gpt_5_1_prompt.md",
+};
+
+/**
+ * Cache file mapping for each model family
+ */
+const CACHE_FILES: Record<ModelFamily, string> = {
+	"codex-max": "codex-max-instructions.md",
+	codex: "codex-instructions.md",
+	"gpt-5.1": "gpt-5.1-instructions.md",
+};
+
+/**
+ * Determine the model family based on the normalized model name
+ * @param normalizedModel - The normalized model name (e.g., "gpt-5.1-codex-max", "gpt-5.1-codex", "gpt-5.1")
+ * @returns The model family for prompt selection
+ */
+export function getModelFamily(normalizedModel: string): ModelFamily {
+	// Order matters - check more specific patterns first
+	if (normalizedModel.includes("codex-max")) {
+		return "codex-max";
+	}
+	if (
+		normalizedModel.includes("codex") ||
+		normalizedModel.startsWith("codex-")
+	) {
+		return "codex";
+	}
+	return "gpt-5.1";
+}
+
 /**
  * Get the latest release tag from GitHub
  * @returns Release tag name (e.g., "rust-v0.43.0")
  */
 async function getLatestReleaseTag(): Promise<string> {
 	const response = await fetch(GITHUB_API_RELEASES);
-	if (!response.ok) throw new Error(`Failed to fetch latest release: ${response.status}`);
+	if (!response.ok)
+		throw new Error(`Failed to fetch latest release: ${response.status}`);
 	const data = (await response.json()) as GitHubRelease;
 	return data.tag_name;
 }
@@ -30,31 +74,49 @@ async function getLatestReleaseTag(): Promise<string> {
  * Always fetches from the latest release tag, not main branch
  *
  * Rate limit protection: Only checks GitHub if cache is older than 15 minutes
- * @returns Codex instructions
+ *
+ * @param normalizedModel - The normalized model name (optional, defaults to "gpt-5.1-codex" for backwards compatibility)
+ * @returns Codex instructions for the specified model family
  */
-export async function getCodexInstructions(): Promise<string> {
+export async function getCodexInstructions(
+	normalizedModel = "gpt-5.1-codex",
+): Promise<string> {
+	const modelFamily = getModelFamily(normalizedModel);
+	const promptFile = PROMPT_FILES[modelFamily];
+	const cacheFile = join(CACHE_DIR, CACHE_FILES[modelFamily]);
+	const cacheMetaFile = join(
+		CACHE_DIR,
+		`${CACHE_FILES[modelFamily].replace(".md", "-meta.json")}`,
+	);
+
 	try {
 		// Load cached metadata (includes ETag, tag, and lastChecked timestamp)
 		let cachedETag: string | null = null;
 		let cachedTag: string | null = null;
 		let cachedTimestamp: number | null = null;
 
-		if (existsSync(CACHE_METADATA_FILE)) {
-			const metadata = JSON.parse(readFileSync(CACHE_METADATA_FILE, "utf8")) as CacheMetadata;
+		if (existsSync(cacheMetaFile)) {
+			const metadata = JSON.parse(
+				readFileSync(cacheMetaFile, "utf8"),
+			) as CacheMetadata;
 			cachedETag = metadata.etag;
 			cachedTag = metadata.tag;
 			cachedTimestamp = metadata.lastChecked;
 		}
 
 		// Rate limit protection: If cache is less than 15 minutes old, use it
 		const CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
-		if (cachedTimestamp && (Date.now() - cachedTimestamp) < CACHE_TTL_MS && existsSync(CACHE_FILE)) {
-			return readFileSync(CACHE_FILE, "utf8");
+		if (
+			cachedTimestamp &&
+			Date.now() - cachedTimestamp < CACHE_TTL_MS &&
+			existsSync(cacheFile)
+		) {
+			return readFileSync(cacheFile, "utf8");
 		}
 
 		// Get the latest release tag (only if cache is stale or missing)
 		const latestTag = await getLatestReleaseTag();
-		const CODEX_INSTRUCTIONS_URL = `https://raw.githubusercontent.com/openai/codex/${latestTag}/codex-rs/core/gpt_5_codex_prompt.md`;
+		const CODEX_INSTRUCTIONS_URL = `https://raw.githubusercontent.com/openai/codex/${latestTag}/codex-rs/core/${promptFile}`;
 
 		// If tag changed, we need to fetch new instructions
 		if (cachedTag !== latestTag) {
@@ -71,8 +133,8 @@ export async function getCodexInstructions(): Promise<string> {
 
 		// 304 Not Modified - our cached version is still current
 		if (response.status === 304) {
-			if (existsSync(CACHE_FILE)) {
-				return readFileSync(CACHE_FILE, "utf8");
+			if (existsSync(cacheFile)) {
+				return readFileSync(cacheFile, "utf8");
 			}
 			// Cache file missing but GitHub says not modified - fall through to re-fetch
 		}
@@ -88,9 +150,9 @@ export async function getCodexInstructions(): Promise<string> {
 			}
 
 			// Cache the instructions with ETag and tag (verbatim from GitHub)
-			writeFileSync(CACHE_FILE, instructions, "utf8");
+			writeFileSync(cacheFile, instructions, "utf8");
 			writeFileSync(
-				CACHE_METADATA_FILE,
+				cacheMetaFile,
 				JSON.stringify({
 					etag: newETag,
 					tag: latestTag,
@@ -107,18 +169,22 @@ export async function getCodexInstructions(): Promise<string> {
 	} catch (error) {
 		const err = error as Error;
 		console.error(
-			"[openai-codex-plugin] Failed to fetch instructions from GitHub:",
+			`[openai-codex-plugin] Failed to fetch ${modelFamily} instructions from GitHub:`,
 			err.message,
 		);
 
 		// Try to use cached version even if stale
-		if (existsSync(CACHE_FILE)) {
-			console.error("[openai-codex-plugin] Using cached instructions");
-			return readFileSync(CACHE_FILE, "utf8");
+		if (existsSync(cacheFile)) {
+			console.error(
+				`[openai-codex-plugin] Using cached ${modelFamily} instructions`,
+			);
+			return readFileSync(cacheFile, "utf8");
 		}
 
-		// Fall back to bundled version
-		console.error("[openai-codex-plugin] Falling back to bundled instructions");
+		// Fall back to bundled version (use codex-instructions.md as default)
+		console.error(
+			`[openai-codex-plugin] Falling back to bundled instructions for ${modelFamily}`,
+		);
 		return readFileSync(join(__dirname, "codex-instructions.md"), "utf8");
 	}
 }

lib/prompts/opencode-codex.ts

@@ -10,7 +10,7 @@ import { homedir } from "node:os";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 
 const OPENCODE_CODEX_URL =
-	"https://raw.githubusercontent.com/sst/opencode/main/packages/opencode/src/session/prompt/codex.txt";
+	"https://raw.githubusercontent.com/sst/opencode/dev/packages/opencode/src/session/prompt/codex.txt";
 const CACHE_DIR = join(homedir(), ".opencode", "cache");
 const CACHE_FILE = join(CACHE_DIR, "opencode-codex.txt");
 const CACHE_META_FILE = join(CACHE_DIR, "opencode-codex-meta.json");