@gajae-code/coding-agent 0.12.21 → 0.13.0

package/dist/types/tools/image-gen.d.ts

@@ -1,8 +1,9 @@
 import { type Model } from "@gajae-code/ai/core";
 import * as z from "zod/v4";
 import { type ModelRegistry } from "../config/model-registry";
+import type { Settings } from "../config/settings";
 import type { CustomTool } from "../extensibility/custom-tools/types";
-type ImageProvider = "alibaba" | "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter";
+type ImageProvider = "alibaba" | "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | (string & {});
 declare const responseModalitySchema: z.ZodEnum<{
     IMAGE: "IMAGE";
     TEXT: "TEXT";
@@ -116,22 +117,17 @@ interface InlineImageData {
     data: string;
     mimeType: string;
 }
-/** Set the preferred image provider from settings */
-export declare function setPreferredImageProvider(provider: ImageProvider | "auto"): void;
-/** Provider → default image model mapping for auto-binding */
+/** Provider → default image model mapping for fallbacks */
 export declare const IMAGE_PROVIDER_DEFAULTS: Record<string, string>;
-/** Resolved image generation configuration from settings */
-export interface ImageProviderConfig {
-    provider: ImageProvider | "auto" | "custom";
-    model: string | null;
-    customUrl?: string;
-    customKey?: string;
-    customKeyEnv?: string;
-}
-/** Set the configured image provider + model from settings */
-export declare function setConfiguredImageModel(config: ImageProviderConfig | null): void;
-/** Get the current configured image model (for UI display) */
-export declare function getConfiguredImageModel(): ImageProviderConfig | null;
+/**
+ * Resolve the image-generation model from the `modelRoles.image` settings entry.
+ * Returns the resolved Model (with provider identity) or undefined when no
+ * image role is configured / no matching model is available.
+ */
+export declare function resolveImageRoleModel(settings: Settings, modelRegistry: ModelRegistry, options?: {
+    sessionId?: string;
+    credentialSessionId?: string;
+}): Model | undefined;
 /** Resolve the effective image model for a configured provider */
 export declare function resolveImageModel(provider: string, modelOverride: string | null): string;
 /** Test seam: the Google image key fallback as resolved from trusted env. */
@@ -140,6 +136,6 @@ export declare function isOpenAIHostedImageModel(model: Model | undefined): mode
 /** Test seam: the image-request base URL as resolved from trusted env. */
 export declare function getOpenAIImageBaseUrlForTest(model: Model, authCredentialType?: "api_key" | "oauth"): string;
 export declare const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails>;
-export declare function getImageGenTools(modelRegistry?: ModelRegistry, activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
-export declare function getImageGenToolsWithRegistry(modelRegistry: ModelRegistry, activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
+export declare function getImageGenTools(modelRegistry?: ModelRegistry, settings?: Settings): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
+export declare function getImageGenToolsWithRegistry(modelRegistry: ModelRegistry, settings: Settings): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;
 export {};

package/dist/types/tools/index.d.ts

@@ -171,6 +171,8 @@ export interface ToolSession {
     requestForegroundBashBackground?: () => boolean;
     /** Get session ID */
     getSessionId?: () => string | null;
+    /** Get credential-selection session identity. */
+    getCredentialSessionId?: () => string | null;
     /** Scope-held MCP facade for mcp:// resolution. */
     getMcpManager?: () => import("../runtime-mcp/manager").MCPManager | undefined;
     /** Whether local:// must use external managed scratch instead of artifacts/local. */

package/dist/types/tools/resource-gc.d.ts

@@ -39,6 +39,8 @@ export interface ResourceGcDeps {
     listTeamWorkers?: (cwd: string, sessionId: string) => Promise<MemoryGuardWorkerSample[]>;
     applyTeamWorkerGuard?: (cwd: string, sessionId: string, workerId: string, excessBytes: number, incidentId: string) => Promise<void>;
 }
+/** Request collection without synchronously stopping the main event loop. */
+export declare function requestMemoryPressureGc(): void;
 export interface ResourceGcRegistration {
     sessionId: string;
     settings: Settings;

package/dist/types/utils/pasted-image-path.d.ts

@@ -32,3 +32,9 @@ export declare function resolvePastedImagePath(text: string, options?: ResolvePa
  */
 export declare function parsePastedImagePaths(text: string, options?: ResolvePastedImagePathOptions): PastedImagePathParseResult | undefined;
 export declare function formatPastedImageReference(placeholder: string, imagePath: string): string;
+export interface PastedImageReferenceRange {
+    imageIndex: number;
+    startCol: number;
+    endCol: number;
+}
+export declare function locatePastedImageReferenceAroundCursor(line: string, cursorCol: number): PastedImageReferenceRange | null;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.12.21",
+	"version": "0.13.0",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -48,19 +48,19 @@
 		"install:defaults": "bun src/cli.ts setup defaults",
 		"verify:insane-vendor": "bun scripts/verify-insane-vendor.ts",
 		"verify:sdk-canonicalization": "bun scripts/verify-gjc-sdk-canonicalization.ts",
-		"check:sdk-closure": "bun ../../scripts/telegram-daemon-generation-guard.ts --validate-current-tree && bun test ../../scripts/telegram-daemon-generation-guard.test.ts && bun scripts/generate-sdk-operation-inventory.ts --check && bun scripts/generate-sdk-adapter-parity-manifest.ts --check && bun scripts/run-test-manifest.ts test/manifests/sdk-adapter-parity-v1.json && bun scripts/generate-telegram-baseline-manifest.ts --check && bun scripts/run-test-manifest.ts test/manifests/telegram-baseline-v1.json && bun test test/sdk-downgrade-rollback.test.ts test/sdk-downgrade-unknown-version.test.ts && bun scripts/verify-gjc-sdk-canonicalization.ts --self-test && bun scripts/verify-gjc-sdk-canonicalization.ts && bun scripts/verify-gjc-sdk-rename.ts"
+		"check:sdk-closure": "bun ../../scripts/telegram-daemon-generation-guard.ts --validate-current-tree && bun test ../../scripts/telegram-daemon-generation-guard.test.ts && bun scripts/generate-sdk-operation-inventory.ts --check && bun scripts/generate-sdk-adapter-parity-manifest.ts --check && GJC_MANIFEST_RECEIPT_CONCURRENCY=8 bun scripts/run-test-manifest.ts test/manifests/sdk-adapter-parity-v1.json && bun scripts/generate-telegram-baseline-manifest.ts --check && bun scripts/run-test-manifest.ts test/manifests/telegram-baseline-v1.json && bun test test/sdk-downgrade-rollback.test.ts test/sdk-downgrade-unknown-version.test.ts && bun scripts/verify-gjc-sdk-canonicalization.ts --self-test && bun scripts/verify-gjc-sdk-canonicalization.ts && bun scripts/verify-gjc-sdk-rename.ts"
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.12.21",
-		"@gajae-code/agent-core": "0.12.21",
-		"@gajae-code/ai": "0.12.21",
-		"@gajae-code/bridge-client": "0.12.21",
-		"@gajae-code/natives": "0.12.21",
-		"@gajae-code/tui": "0.12.21",
-		"@gajae-code/utils": "0.12.21",
+		"@gajae-code/stats": "0.13.0",
+		"@gajae-code/agent-core": "0.13.0",
+		"@gajae-code/ai": "0.13.0",
+		"@gajae-code/bridge-client": "0.13.0",
+		"@gajae-code/natives": "0.13.0",
+		"@gajae-code/tui": "0.13.0",
+		"@gajae-code/utils": "0.13.0",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/generate-sdk-operation-inventory.ts

@@ -35,6 +35,14 @@ const LOCKED_EXCLUSIONS: Readonly<Record<string, string>> = {
 	"slash_command:transcript": "visual/local-only transcript viewer, not a user-facing SDK control seam",
 	"slash_command:sessions": "visual/local-only sessions dashboard, not a user-facing SDK control seam",
 	"agent_session:constructor": "internal accessor/plumbing, not a user-facing control seam",
+	"agent_session:getConfiguredModelChainState":
+		"internal model-profile transaction snapshot, not a user-facing SDK control seam",
+	"agent_session:getDefaultFallbackRuntimeState":
+		"internal model-profile transaction snapshot, not a user-facing SDK control seam",
+	"agent_session:restoreDefaultFallbackRuntimeState":
+		"internal rollback compensation, not a user-facing SDK control seam",
+	"agent_session:restoreModelSelectionForRollback":
+		"internal rollback compensation, not a user-facing SDK control seam",
 	"agent_session:materializeActiveDefaultModelProfileAssignment":
 		"internal extension selection materialization seam, not a user-facing SDK control seam",
 	"agent_session:registerToolSessionCleanup":

package/scripts/run-test-manifest.ts

@@ -115,41 +115,81 @@ if (rows.length > 0) {
 if (checkOnly) process.exit(0);
 
 const startedAt = performance.now();
-let commandReceipts = 0;
-let rowReceipts = 0;
 const perAdapter = new Map<string, number>();
 
-async function executeReceipt(argv: string[]): Promise<void> {
+/**
+ * A receipt is already an isolated `bun test` process, so a manifest whose
+ * receipts are independent can run them through a bounded worker pool instead of
+ * one at a time — which is what made this gate the dominant cost of `check:ts`,
+ * a few hundred process startups serialized behind each other. Independence is
+ * not free, though: receipts that each spawn a detached SDK broker and load
+ * Node-API addons fail when they race, so concurrency is never assumed. It stays
+ * sequential unless the caller opts a specific manifest in through
+ * `GJC_MANIFEST_RECEIPT_CONCURRENCY`, and every receipt keeps its own process,
+ * its own argv, and its own receipt line either way.
+ */
+const receiptConcurrency = (() => {
+	const configured = Number(process.env.GJC_MANIFEST_RECEIPT_CONCURRENCY);
+	return Number.isSafeInteger(configured) && configured >= 1 ? configured : 1;
+})();
+
+type ReceiptOutcome = { stdout: string; stderr: string; exitCode: number; tests: number | undefined };
+
+function satisfiesReceipt(outcome: ReceiptOutcome): boolean {
+	return outcome.exitCode === 0 && outcome.tests !== undefined && outcome.tests >= 1;
+}
+
+async function runReceipt(argv: string[]): Promise<ReceiptOutcome> {
 	const child = Bun.spawn(argv, { cwd: repoRoot, stdout: "pipe", stderr: "pipe" });
 	const [stdout, stderr, exitCode] = await Promise.all([
 		new Response(child.stdout).text(),
 		new Response(child.stderr).text(),
 		child.exited,
 	]);
-	process.stdout.write(stdout);
-	process.stderr.write(stderr);
-	const tests = testCount(`${stdout}\n${stderr}`);
-	process.stdout.write(`receipt: ${argv.join(" ")} exit=${exitCode} tests=${tests ?? "unknown"}\n`);
-	if (exitCode === 0 && tests !== undefined && tests >= 1) return;
-	const reason = exitCode !== 0 ? `exit ${exitCode}` : "did not report at least one test";
-	process.stderr.write(`Manifest receipt failed: ${argv.join(" ")} (${reason})\n`);
-	process.exit(1);
+	return { stdout, stderr, exitCode, tests: testCount(`${stdout}\n${stderr}`) };
 }
 
-for (const command of manifest.commands) {
-	await executeReceipt(command.argv);
-	commandReceipts++;
+/**
+ * Runs one phase to completion and then reports it in manifest order. A failing
+ * receipt stops the pool from claiming further work and exits non-zero, so the
+ * gate still fails closed; receipts already in flight are drained rather than
+ * abandoned, and receipts that were never claimed are never reported as evidence.
+ */
+async function executePhase(argvs: string[][]): Promise<void> {
+	const outcomes = new Array<ReceiptOutcome | undefined>(argvs.length);
+	let claimed = 0;
+	let stopped = false;
+	const drain = async (): Promise<void> => {
+		for (;;) {
+			const index = claimed++;
+			if (stopped || index >= argvs.length) return;
+			const outcome = await runReceipt(argvs[index]!);
+			outcomes[index] = outcome;
+			if (!satisfiesReceipt(outcome)) stopped = true;
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(receiptConcurrency, argvs.length) }, drain));
+	for (const [index, argv] of argvs.entries()) {
+		const outcome = outcomes[index];
+		if (!outcome) continue;
+		process.stdout.write(outcome.stdout);
+		process.stderr.write(outcome.stderr);
+		process.stdout.write(`receipt: ${argv.join(" ")} exit=${outcome.exitCode} tests=${outcome.tests ?? "unknown"}\n`);
+		if (satisfiesReceipt(outcome)) continue;
+		const reason = outcome.exitCode !== 0 ? `exit ${outcome.exitCode}` : "did not report at least one test";
+		process.stderr.write(`Manifest receipt failed: ${argv.join(" ")} (${reason})\n`);
+		process.exit(1);
+	}
 }
-process.stdout.write(`manifest command receipts complete: ${commandReceipts}\n`);
 
-for (const row of rows) {
-	await executeReceipt(row.argv);
-	rowReceipts++;
-	perAdapter.set(row.adapter, (perAdapter.get(row.adapter) ?? 0) + 1);
-}
+await executePhase(manifest.commands.map(command => command.argv));
+process.stdout.write(`manifest command receipts complete: ${manifest.commands.length}\n`);
+
+await executePhase(rows.map(row => row.argv));
+for (const row of rows) perAdapter.set(row.adapter, (perAdapter.get(row.adapter) ?? 0) + 1);
 if (rows.length > 0) {
 	process.stdout.write(
-		`manifest row receipts complete: ${rowReceipts} (${[...perAdapter].map(([adapter, count]) => `${adapter}=${count}`).join(", ")})\n`,
+		`manifest row receipts complete: ${rows.length} (${[...perAdapter].map(([adapter, count]) => `${adapter}=${count}`).join(", ")})\n`,
 	);
 }
 process.stdout.write(`manifest receipts runtime=${Math.round(performance.now() - startedAt)}ms\n`);

package/scripts/verify-gjc-sdk-canonicalization.ts

@@ -1635,14 +1635,14 @@ function lineNumber(contents: string, offset: number): number {
 const machineEntrypoints = new Map<string, string>([
 	["packages/coding-agent/src/modes/acp/acp-agent.ts", "ACP"],
 	["packages/coding-agent/src/commands/mcp-serve.ts", "MCP"],
-	["packages/coding-agent/src/sdk/cli/session-cli.ts", "daemon session CLI"],
+	["packages/coding-agent/src/sdk/cli/session-cli.ts", "sdk session CLI"],
 ]);
 
 const machineWrapperEntrypoints = new Map<string, string>([
 	["packages/coding-agent/src/commands/acp.ts", "ACP command"],
 	["packages/coding-agent/src/commands/daemon.ts", "daemon command"],
 	["packages/coding-agent/src/commands/mcp-serve.ts", "MCP command"],
-	["packages/coding-agent/src/sdk/cli/session-cli.ts", "daemon session CLI"],
+	["packages/coding-agent/src/sdk/cli/session-cli.ts", "sdk session CLI"],
 ]);
 const rootAcpEntrypoint = "packages/coding-agent/src/main.ts";
 const directMachineWrapperRoutePattern =
@@ -1938,9 +1938,14 @@ async function scan(): Promise<string[]> {
 				violations.push(`${file}: shipped ACP command does not dispatch through the root ACP bootstrap`);
 			}
 		}
-		if (file === "packages/coding-agent/src/commands/daemon.ts") {
+		if (file === "packages/coding-agent/src/commands/sdk.ts") {
 			if (!/runSdkSessionCli\s*\(/.test(contents)) {
-				violations.push(`${file}: shipped daemon session command does not dispatch the SDK session CLI`);
+				violations.push(`${file}: shipped sdk session command does not dispatch the SDK session CLI`);
+			}
+		}
+		if (file === "packages/coding-agent/src/commands/daemon.ts") {
+			if (/\brawAction\s*===\s*["']session["']|\baction:\s*["']session["']\s*[,}]/.test(contents)) {
+				violations.push(`${file}: daemon command retained removed SDK session routing`);
 			}
 		}
 		if (file === "packages/coding-agent/src/modes/acp/acp-agent.ts") {

package/src/cli/args.ts

@@ -7,9 +7,34 @@ import { logger } from "@gajae-code/utils";
 import { CliParseError } from "@gajae-code/utils/cli";
 import { parseEffort } from "../thinking";
 import { BUILTIN_TOOLS } from "../tools";
+import { type ConsumerLaunchFlagName, LAUNCH_PARSE_FLAGS, launchFlagIsOwnedBy } from "./root-flags";
+
+const ROOT_FLAG_TOKENS = new Set<string>();
+for (const [name, descriptor] of Object.entries(LAUNCH_PARSE_FLAGS)) {
+	ROOT_FLAG_TOKENS.add(`--${name}`);
+	if (descriptor.char) ROOT_FLAG_TOKENS.add(`-${descriptor.char}`);
+}
+
+const INTERNAL_ROOT_FLAG_TOKENS = new Set(["--help", "-h", "--version", "-v", "--session", "--provider-session-id"]);
+
+function isExternallyParsedRootFlagToken(arg: string): boolean {
+	return (
+		arg === "--acp-terminal-auth" ||
+		arg === "--worktree" ||
+		arg === "-w" ||
+		arg.startsWith("-w=") ||
+		arg.startsWith("-w")
+	);
+}
+
+function isKnownRootFlagToken(arg: string): boolean {
+	return ROOT_FLAG_TOKENS.has(arg) || INTERNAL_ROOT_FLAG_TOKENS.has(arg) || isExternallyParsedRootFlagToken(arg);
+}
 
 export type Mode = "text" | "json" | "acp";
 
+export type ParseArgsAuthority = "local" | "acp" | "deferred";
+
 export interface Args {
 	cwd?: string;
 	allowHome?: boolean;
@@ -58,12 +83,14 @@ export interface Args {
 	noTitle?: boolean;
 	messages: string[];
 	fileArgs: string[];
-	/** Retained for test/runtime compatibility; extension-defined flags are no longer parsed. */
+	/** Flags unknown to every launch parser; their consumer supplies the diagnostic. */
 	unknownFlags: Map<string, boolean | string>;
 	/** Exact interactive startup login intent, recognized before model-profile activation. */
 	authBootstrap?: true;
 }
 
+const CONSUMER_FLAGS_BY_ARGS = new WeakMap<Args, Map<ConsumerLaunchFlagName, string>>();
+
 function isStartupSlashCommandArg(arg: string | undefined): boolean {
 	return (
 		arg === "/provider" ||
@@ -99,12 +126,13 @@ function takePromptValue(
 	return takeFlagValue(args, index, flag, allowInlineDashPrefixed || allowSeparatedDashPrefixed);
 }
 
-export function parseArgs(args: string[]): Args {
+export function parseArgs(args: string[], authority: ParseArgsAuthority = "local"): Args {
 	const result: Args = {
 		messages: [],
 		fileArgs: [],
 		unknownFlags: new Map(),
 	};
+	const consumerFlags = new Map<ConsumerLaunchFlagName, string>();
 
 	for (let i = 0; i < args.length; i++) {
 		let arg = args[i];
@@ -120,6 +148,13 @@ export function parseArgs(args: string[]): Args {
 			result.messages.push(args.slice(i).join(" "));
 			break;
 		}
+		if (arg === "--") {
+			for (const positional of args.slice(i + 1)) {
+				if (positional.startsWith("@")) result.fileArgs.push(positional.slice(1));
+				else result.messages.push(positional);
+			}
+			break;
+		}
 
 		// Support --flag=value syntax (e.g. --tools=ask,read)
 		if (arg.startsWith("--") && arg.includes("=")) {
@@ -130,6 +165,11 @@ export function parseArgs(args: string[]): Args {
 			// Insert the value so the existing "args[++i]" logic picks it up
 			args.splice(i + 1, 0, value);
 		}
+		if (arg.startsWith("-") && !isKnownRootFlagToken(arg)) {
+			result.unknownFlags.set(arg, true);
+			if (hasInlineValue) i++;
+			continue;
+		}
 
 		if (arg === "--help" || arg === "-h") {
 			result.help = true;
@@ -239,18 +279,23 @@ export function parseArgs(args: string[]): Args {
 		} else if (arg === "--extension" || arg === "-e") {
 			const extension = takeFlagValue(args, i++, "--extension");
 			result.extensions = [...(result.extensions ?? []), extension];
+			consumerFlags.set("extension", "--extension");
 		} else if (arg === "--hook") {
 			const hook = takeFlagValue(args, i++, "--hook");
 			result.hooks = [...(result.hooks ?? []), hook];
+			consumerFlags.set("hook", "--hook");
 		} else if (arg === "--no-extensions") {
 			result.noExtensions = true;
+			consumerFlags.set("no-extensions", "--no-extensions");
 		} else if (arg === "--no-skills") {
 			result.noSkills = true;
+			consumerFlags.set("no-skills", "--no-skills");
 		} else if (arg === "--skills") {
 			result.skills = takeFlagValue(args, i++, "--skills")
 				.split(",")
 				.map(s => s.trim())
 				.filter(Boolean);
+			consumerFlags.set("skills", "--skills");
 		} else if (arg === "--tools") {
 			const toolNames = takeFlagValue(args, i++, "--tools")
 				.split(",")
@@ -302,24 +347,32 @@ export function parseArgs(args: string[]): Args {
 			}
 		} else if (arg.startsWith("@")) {
 			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
-		} else if (arg.startsWith("-")) {
-			result.unknownFlags.set(arg, true);
-		} else {
+		} else if (!arg.startsWith("-")) {
 			result.messages.push(arg);
+		} else if (!isExternallyParsedRootFlagToken(arg)) {
+			throw new CliParseError(`Root option is declared but not parsed: ${arg}`);
 		}
 	}
 
 	if (result.default && !result.mpreset) {
 		throw new CliParseError("--default requires --mpreset <name>");
 	}
-	if (
-		result.mcpConfig !== undefined &&
-		(result.mode === "acp" || result.listModels !== undefined || result.export !== undefined)
-	) {
+	if (result.mcpConfig !== undefined && (result.listModels !== undefined || result.export !== undefined)) {
 		throw new CliParseError(
 			"--mcp-config is only supported in standalone interactive, tmux, print, text, or json modes.",
 		);
 	}
 
+	CONSUMER_FLAGS_BY_ARGS.set(result, consumerFlags);
+	if (authority === "local") assertLocalLaunchArgs(result);
 	return result;
 }
+
+/** Reject flags whose only owners are non-local startup consumers. */
+export function assertLocalLaunchArgs(parsed: Args): void {
+	const unknown = parsed.unknownFlags.keys().next().value;
+	if (unknown) throw new CliParseError(`Unknown option: ${unknown}`);
+	for (const [name, token] of CONSUMER_FLAGS_BY_ARGS.get(parsed) ?? []) {
+		if (!launchFlagIsOwnedBy(name, "local")) throw new CliParseError(`Unknown option: ${token}`);
+	}
+}

package/src/cli/completion-cli.ts

@@ -107,6 +107,7 @@ function figOptionFromFlag(name: string, descriptor: FlagDescriptor): FigOption
 		const arg: FigArg = { name: optionArgName(name, descriptor) };
 		const suggestions = argSuggestions(descriptor.options);
 		if (suggestions) arg.suggestions = suggestions;
+		if (descriptor.optionalValue) arg.isOptional = true;
 		option.args = arg;
 	}
 	return option;

package/src/cli/fast-help.ts

@@ -30,6 +30,7 @@ export function getExtraHelpText(): string {
   ${APP_NAME} web-search           - Search the web from the CLI (alias: q)
   ${APP_NAME} codex-native-hook    - Run Codex native hook integration
   ${APP_NAME} gc                   - Run garbage-collection/cleanup helpers
+  ${APP_NAME} quick-lane         - Classify a task into quick lane or deep path
   ${APP_NAME} <command> --help     - Show command-specific help
 
 Environment Variables:

package/src/cli/root-flags.ts

@@ -0,0 +1,100 @@
+import { type FlagDescriptor, Flags } from "@gajae-code/utils/cli";
+
+const ROOT_THINKING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+/** Public launch flags shared by root help, completion, and the launch command. */
+export const ROOT_LAUNCH_FLAGS = {
+	model: Flags.string({ description: 'Model to use (fuzzy match: "opus", "gpt-5.2", or "openai/gpt-5.2")' }),
+	smol: Flags.string({ description: "Smol/fast model for lightweight tasks (or GJC_SMOL_MODEL env)" }),
+	slow: Flags.string({ description: "Slow/reasoning model for thorough analysis (or GJC_SLOW_MODEL env)" }),
+	plan: Flags.string({ description: "Plan model for architectural planning (or GJC_PLAN_MODEL env)" }),
+	mpreset: Flags.string({ description: "Model profile preset to activate for this session" }),
+	default: Flags.boolean({ description: "Persist --mpreset as the default model profile" }),
+	provider: Flags.string({ description: "Provider to use (legacy; prefer --model)" }),
+	"api-key": Flags.string({ description: "API key (defaults to env vars)" }),
+	credential: Flags.string({
+		description:
+			"Stored credential selector: email:<addr>, id:<n>, account:<id>, project:<id>, or provider/email:<addr>",
+	}),
+	"system-prompt": Flags.string({ description: "System prompt (default: coding assistant prompt)" }),
+	"append-system-prompt": Flags.string({ description: "Append text or file contents to the system prompt" }),
+	"mcp-config": Flags.string({ description: "Tools-only MCP config file (absolute path)" }),
+	"clipboard-transport": Flags.string({
+		description: "Clipboard transport: auto (default), native, osc52, or ssh",
+		options: ["auto", "native", "osc52", "ssh"],
+	}),
+	"clipboard-ssh-host": Flags.string({
+		description: "SSH host alias for --clipboard-transport ssh (from ~/.ssh/config)",
+	}),
+	"allow-home": Flags.boolean({ description: "Allow starting in ~ without auto-switching to a temp dir" }),
+	mode: Flags.string({
+		description: "Output mode: text (default), json, or acp",
+		options: ["text", "json", "acp"],
+	}),
+	print: Flags.boolean({ char: "p", description: "Non-interactive mode: process prompt and exit" }),
+	continue: Flags.boolean({ char: "c", description: "Continue previous session" }),
+	resume: Flags.string({
+		char: "r",
+		description: "Resume a session (by ID prefix, path, or picker if omitted)",
+		optionalValue: true,
+	}),
+	fork: Flags.string({ description: "Fork a session (by ID prefix or path)" }),
+	worktree: Flags.string({
+		char: "w",
+		description: "Launch in a managed worktree (optional branch name)",
+		optionalValue: true,
+	}),
+	"session-dir": Flags.string({
+		description: "Explicit session storage directory and lookup override (default uses managed v2 workspace scope)",
+	}),
+	"no-session": Flags.boolean({ description: "Don't save session (ephemeral)" }),
+	models: Flags.string({ description: "Comma-separated model patterns for Alt+N cycling" }),
+	"no-tools": Flags.boolean({ description: "Disable all built-in tools" }),
+	"no-lsp": Flags.boolean({ description: "Disable LSP tools, formatting, and diagnostics" }),
+	"no-pty": Flags.boolean({ description: "Disable PTY-based interactive bash execution" }),
+	tmux: Flags.boolean({ description: "Launch interactive startup inside tmux" }),
+	tools: Flags.string({ description: "Comma-separated list of tools to enable (default: all)" }),
+	thinking: Flags.string({
+		description: `Set thinking level: ${ROOT_THINKING_EFFORTS.join(", ")}`,
+		options: ROOT_THINKING_EFFORTS,
+	}),
+	"no-rules": Flags.boolean({ description: "Disable rules discovery and loading" }),
+	export: Flags.string({ description: "Export session file to HTML and exit" }),
+	"list-models": Flags.string({
+		description: "List available models (with optional fuzzy search)",
+		optionalValue: true,
+	}),
+	"no-title": Flags.boolean({ description: "Disable title auto-generation" }),
+};
+
+export type ConsumerLaunchFlagName = "hook" | "extension" | "no-extensions" | "no-skills" | "skills";
+
+export type LaunchFlagConsumer = "acp" | "local";
+
+/**
+ * Flags accepted only so their owning startup consumer can classify them. They
+ * deliberately stay out of root help and completion.
+ */
+export const CONSUMER_LAUNCH_FLAGS: Record<ConsumerLaunchFlagName, FlagDescriptor> = {
+	hook: Flags.string({ multiple: true }),
+	extension: Flags.string({ char: "e", multiple: true }),
+	"no-extensions": Flags.boolean(),
+	"no-skills": Flags.boolean(),
+	skills: Flags.string(),
+};
+
+/** Every flag understood by the launch argument parser, including hidden consumer-owned flags. */
+export const LAUNCH_PARSE_FLAGS = { ...ROOT_LAUNCH_FLAGS, ...CONSUMER_LAUNCH_FLAGS };
+
+/** Startup consumers that may receive a hidden launch flag. */
+export const LAUNCH_FLAG_CONSUMERS: Record<ConsumerLaunchFlagName, readonly LaunchFlagConsumer[]> = {
+	hook: ["acp"],
+	extension: ["acp"],
+	"no-extensions": ["acp"],
+	"no-skills": ["acp", "local"],
+	skills: ["acp"],
+};
+
+export function launchFlagIsOwnedBy(name: ConsumerLaunchFlagName, consumer: LaunchFlagConsumer): boolean {
+	return LAUNCH_FLAG_CONSUMERS[name].includes(consumer);
+}

package/src/cli/setup-cli.ts

@@ -496,7 +496,7 @@ async function handlePythonSetup(flags: { json?: boolean; check?: boolean }): Pr
 }
 
 async function handleSttSetup(flags: { json?: boolean; check?: boolean }): Promise<void> {
-	const { checkDependencies, formatDependencyStatus } = await import("../stt/setup");
+	const { checkDependencies, formatDependencyStatus, formatSTTUsage } = await import("../stt/setup");
 	const status = await checkDependencies();
 
 	if (flags.json) {
@@ -509,6 +509,7 @@ async function handleSttSetup(flags: { json?: boolean; check?: boolean }): Promi
 
 	if (status.recorder.available && status.python.available && status.whisper.available) {
 		console.log(chalk.green(`\n${theme.status.success} Speech-to-text is ready`));
+		console.log(`\n${formatSTTUsage()}`);
 		return;
 	}
 
@@ -542,6 +543,7 @@ async function handleSttSetup(flags: { json?: boolean; check?: boolean }): Promi
 	const recheck = await checkDependencies();
 	if (recheck.recorder.available && recheck.python.available && recheck.whisper.available) {
 		console.log(chalk.green(`\n${theme.status.success} Speech-to-text is ready`));
+		console.log(`\n${formatSTTUsage()}`);
 	} else {
 		console.error(chalk.red(`\n${theme.status.error} Setup incomplete`));
 		console.log(formatDependencyStatus(recheck));
@@ -733,6 +735,8 @@ ${chalk.bold("Provider example:")}
   ${APP_NAME} setup provider --preset glm
   ${APP_NAME} setup provider --preset cline-pass
   ${APP_NAME} setup provider --preset commandcode-goat
+  ${APP_NAME} setup provider --preset litellm --base-url https://litellm.example.com/v1
+  ${APP_NAME} setup provider --preset openai-compatible-proxy --base-url https://gateway.example.com/v1
   MY_PROVIDER_KEY=sk-... ${APP_NAME} setup provider --compat openai --provider my-oai --base-url https://api.example.com/v1 --api-key-env MY_PROVIDER_KEY --model gpt-example
 
 ${chalk.bold("Hermes example:")}
@@ -748,7 +752,7 @@ ${chalk.bold("Options:")}
   --preset          Provider preset id (run setup provider --help to list available presets)
   --compat          Provider compatibility: openai or anthropic
   --provider        Provider id to add to models.yml
-  --base-url        Provider API base URL
+  --base-url        Provider API base URL (required for proxy presets: litellm, openai-compatible-proxy)
   --api-key-env     Read provider API key from this environment variable
   --model, --models Model id to add (repeat or comma-separate)
   --models-path     Override models config path