@f5-sales-demo/xcsh 20.2.7 → 20.3.0

package/CHANGELOG.md

@@ -1,6 +1,41 @@
+<!-- markdownlint-configure-file { "MD024": { "siblings_only": true } } -->
+
 # Changelog
 
-## [Unreleased]
+## [20.3.0] - 2026-08-04
+
+### Added
+
+- Added a live rotating model benchmark matrix for xcsh TTFT, completion timing, token usage, throughput, correctness, and failure capture ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Added a progressive three-model scenario library for identity, built-in tools, plugin skills and tools, authenticated F5 XC context, and read-only GitHub, Azure, GitLab, Salesforce, and MEDDPICC contracts ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Added per-effort benchmark matrices for low, medium, high, xhigh, and max reasoning, including requested-to-effective effort reporting, provider-error fail-fast capture, deterministic output grading, and explicit unavailability instead of ranking failed providers ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Added explicit `--context <name>` launch selection for reproducible non-interactive and benchmark sessions ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Added `--no-memories` for hermetic sessions that must not load or maintain persisted project memory ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Allowed `--tools` to select plugin and extension tools after runtime discovery ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+
+### Changed
+
+- Changed the binary production default to LiteLLM GPT-5.6 Sol with High reasoning, including Low and High effort role defaults for lightweight and thinking work ([#2886](https://github.com/f5-sales-demo/xcsh/issues/2886))
+
+### Fixed
+
+- Made Office gateway configuration defer a blank model to xcsh's GPT-5.6 Sol default, preserve OpenAI-compatible URL paths, and ignore legacy Anthropic-era saved settings ([#2890](https://github.com/f5-sales-demo/xcsh/issues/2890))
+- Added a deterministic five-step MEDDPICC Office/Excel certification harness with live-model, plugin, filesystem, host-tool, workbook, and idempotency evidence ([#2890](https://github.com/f5-sales-demo/xcsh/issues/2890))
+- Rejected invalid lazy-command syntax before loading heavy command implementations while preserving command-specific launch-flag diagnostics ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Added dependency-install verification and automatic repair so stale workspace links and release-bumped lock entries cannot silently load SDK versions older than manifests, and aligned development with Bun 1.3.14 ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Reconciled out-of-band worker bridge shutdowns even while the process is still draining or unreaped, so immediate reprovisioning cannot retain a dead session ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Isolated live model benchmarks from persisted project memory so unrelated mandatory reads cannot contaminate tool-compliance results ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Refreshed entitlement-scoped OAuth credentials before model discovery so newly available Antigravity models remain resolvable after access-token expiry ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Kept extension-injected and hidden context before the active prompt so the user's explicit instruction remains the final provider input ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Waited for runtime model discovery before resolving explicit model selectors and model scopes ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Preserved the launch directory for `bun run dev` and excluded non-display extension context from JSON output ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Made explicit tool scopes, including `--no-tools`, exclude the bundled image-generation tool even when image credentials are configured ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Made explicit tool scopes authoritative for built-in, custom, and extension-provided tools ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Preserved exact collection counts in model-visible `xcsh_api` output even when large response bodies are truncated ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Made `plugin upgrade --dry-run` fetch current catalogs without changing marketplace registries, persistent caches, installed plugins, timestamps, manifests, or lockfiles ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Migrated generated LiteLLM configuration to schema v4 from literal credentials as well as environment variables while preserving custom API base paths ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Stored live benchmark reports under the private xcsh data directory with collision-resistant filenames by default and resolved context-quality criteria from the selected context so concurrent reports cannot overwrite each other and source never hard-codes live tenant identifiers ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
+- Matched selected benchmark context names as case-insensitive literal text so CLI input cannot become an executable regular expression ([#2874](https://github.com/f5-sales-demo/xcsh/issues/2874))
 
 ## [20.2.5] - 2026-08-02
 
@@ -228,6 +263,7 @@
 
 - Autoresearch subsystem code quality: -513 lines (18.8% reduction), ~13% faster type checking. Un-exported internal symbols, relocated types, consolidated duplicate patterns, replaced manual deep copies with `structuredClone`, replaced `while(exec)` with `matchAll`, compressed control flow, extracted shared interfaces ([#734](https://github.com/f5-sales-demo/xcsh/pull/734))
 
+<!-- markdownlint-disable-next-line MD024 -->
 ## [18.53.0] - 2026-05-09
 
 ### Fixed
@@ -637,6 +673,7 @@ Refs: #173.
 - `/autoresearch` toggles like `/plan` when empty; slash completion no longer suggests `off`/`clear` on an empty prefix after the command
 - Chunk-mode read/edit edge cases (zero-width gap replaces, stale batch diagnostics, grouped Go receivers, line-count headers, parse error locations)
 
+<!-- markdownlint-disable-next-line MD024 -->
 ### Added
 
 - `/review` command now accepts inline args as custom instructions appended to the generated prompt for all structured review modes (PR-style, uncommitted, specific commit). When inline args are provided, option 4 (editor) is suppressed from the menu. The no-UI (Task tool) path forwards args as a focus hint.
@@ -1044,10 +1081,12 @@ Refs: #173.
 - Fixed autoresearch logging to require durable ASI metadata (hypothesis, rollback_reason, next_action_hint) for every run including rollback context for discarded, crashed, and checks-failed experiments
 - Fixed autoresearch logging to require durable ASI metadata for every run, including rollback context for discarded, crashed, and checks-failed experiments
 
+<!-- markdownlint-disable-next-line MD024 -->
 ### Fixed
 
 - Fixed resumed and session-switched GitHub Copilot/OpenAI Responses conversations replaying stale assistant native history from older saved sessions by sanitizing persisted assistant replay metadata on rehydration and resetting provider session state across live session boundaries ([#505](https://github.com/can1357/oh-my-pi/issues/505))
 
+<!-- markdownlint-disable-next-line MD024 -->
 ### Added
 
 - Session observer overlay (`Ctrl+S`): view running subagent sessions with a picker and read-only transcript showing thinking, text, tool calls, and results
@@ -1278,6 +1317,7 @@ Refs: #173.
 
 - Path resolution on Linux redirects to XDG locations when `XDG_DATA_HOME` / `XDG_STATE_HOME` / `XDG_CACHE_HOME` environment variables are set
 
+<!-- markdownlint-disable-next-line MD024 -->
 ### Changed
 
 - Changed TTSR interrupt logic to respect per-rule `interruptMode` settings, falling back to global `ttsr.interruptMode` when rule-level override is not specified
@@ -5453,6 +5493,7 @@ Refs: #173.
 
 - Removed `submit_review` tool - reviewers now finish via `complete` tool with structured output
 
+<!-- markdownlint-disable-next-line MD024 -->
 ### Fixed
 
 - Fixed session persistence to call fsync before renaming temp file for durability
@@ -5564,6 +5605,7 @@ Refs: #173.
 - Added support for file-based slash commands from `commands/` directories
 - Added `$ARGUMENTS` placeholder for slash command argument substitution, aligning with Claude and Codex conventions
 
+<!-- markdownlint-disable-next-line MD024 -->
 ### Changed
 
 - Refactored tool renderers to be colocated with their respective tool implementations for improved code organization

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "20.2.7",
+	"version": "20.3.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -31,11 +31,14 @@
 		"xcsh": "src/cli.ts"
 	},
 	"scripts": {
+		"prebuild": "bun ../../scripts/check-installed-dependencies.ts",
 		"build": "bun run generate-build-info && bun run generate-extension-capabilities && test -f src/internal-urls/api-spec-index.generated.ts && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../office-pane scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset && bun --cwd=../office-pane scripts/generate-client-bundle.ts --reset",
+		"precheck": "bun ../../scripts/check-installed-dependencies.ts",
 		"check": "biome check . && bun run format-prompts -- --check && bun run check:types",
 		"check:types": "bun run generate-build-info && tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"check:bundle": "bun scripts/check-bundle.ts",
+		"pretest": "bun ../../scripts/check-installed-dependencies.ts",
 		"test": "bun run generate-build-info && bun scripts/bun-test-guarded.ts --max-concurrency 1",
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index && bun run generate-api-spec-index && bun run generate-build-info",
 		"fmt": "biome format --write . && bun run format-prompts",
@@ -57,13 +60,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "20.2.7",
-		"@f5-sales-demo/pi-agent-core": "20.2.7",
-		"@f5-sales-demo/pi-ai": "20.2.7",
-		"@f5-sales-demo/pi-natives": "20.2.7",
-		"@f5-sales-demo/pi-resource-management": "20.2.7",
-		"@f5-sales-demo/pi-tui": "20.2.7",
-		"@f5-sales-demo/pi-utils": "20.2.7",
+		"@f5-sales-demo/xcsh-stats": "20.3.0",
+		"@f5-sales-demo/pi-agent-core": "20.3.0",
+		"@f5-sales-demo/pi-ai": "20.3.0",
+		"@f5-sales-demo/pi-natives": "20.3.0",
+		"@f5-sales-demo/pi-resource-management": "20.3.0",
+		"@f5-sales-demo/pi-tui": "20.3.0",
+		"@f5-sales-demo/pi-utils": "20.3.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/browser/chat-handler.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AssistantMessage, ImageContent } from "@f5-sales-demo/pi-ai";
+import { parseModelString } from "../config/model-resolver";
 import { settings } from "../config/settings";
 import { DEFAULT_MODEL_ROLE } from "../config/settings-schema";
 import { toSkillSummaries } from "../extensibility/skills";
@@ -376,13 +377,16 @@ export class ChatHandler {
 	 * SQLite credential store. Mirrors #handleSetHostTools's try/ack-or-nack shape;
 	 * never throws out of the handler (a nack keeps a waiting client from hanging).
 	 *
-	 * The baked F5 gateway registers its models under the "anthropic" provider
-	 * (DEFAULT_MODEL_ROLE = "anthropic/claude-opus-5"), so that is the provider we
-	 * (re)configure here. */
+	 * The baked production role identifies the concrete provider, model, and effort,
+	 * so the bridge follows the same LiteLLM default as every other xcsh entry point. */
 	async #handleConfigure(msg: Configure): Promise<void> {
 		try {
 			const registry = this.#session.modelRegistry;
-			const [provider, defaultModelId] = DEFAULT_MODEL_ROLE.split("/");
+			const defaultModel = parseModelString(DEFAULT_MODEL_ROLE);
+			if (!defaultModel) {
+				throw new Error("Invalid baked default model selector");
+			}
+			const { provider, id: defaultModelId, thinkingLevel } = defaultModel;
 
 			if (msg.baseUrl) {
 				// SSRF guard: only an `https:` gateway URL may be dialed. Validate BEFORE
@@ -401,12 +405,12 @@ export class ChatHandler {
 				// baseUrl + apiKey, no models[] → sets the in-memory runtime API key AND
 				// overrides the existing provider models' baseUrl/headers (reusing their
 				// metadata). Nothing is persisted to disk.
+				registry.authStorage.setRuntimeApiKey(provider, msg.token);
 				registry.registerProvider(
 					provider,
 					{
 						baseUrl,
 						apiKey: msg.token,
-						headers: { "anthropic-beta": "context-1m-2025-08-07" },
 					},
 					"office-configure",
 				);
@@ -415,13 +419,21 @@ export class ChatHandler {
 				registry.authStorage.setRuntimeApiKey(provider, msg.token);
 			}
 
-			const modelId = msg.model ?? this.#session.model?.id ?? defaultModelId;
+			const currentDefaultModelId =
+				this.#session.model?.provider === provider ? this.#session.model.id : defaultModelId;
+			const modelId = msg.model ?? currentDefaultModelId;
 			const model = registry.find(provider, modelId);
 			if (!model) {
 				throw new Error(`No model ${provider}/${modelId} available`);
 			}
 			// setModel validates the API key and throws if missing → becomes configure_error.
-			await this.#session.setModel(model);
+			await this.#session.setModel(model, "default", {
+				selector: `${provider}/${modelId}`,
+				thinkingLevel,
+			});
+			if (thinkingLevel) {
+				this.#session.setThinkingLevel(thinkingLevel);
+			}
 
 			this.#server.send({ type: "configure_ack", model: model.id } satisfies ConfigureAck);
 		} catch {

package/src/browser/chat-protocol.ts

@@ -279,8 +279,8 @@ export interface SetHostToolsError {
 // ---------------------------------------------------------------------------
 
 /** Inbound: the client configures the LLM provider. `token` is required and
- * non-empty. `baseUrl` (optional) is an Anthropic-compatible gateway base; when
- * omitted, the baked F5 gateway is reused and only the runtime API key is set.
+ * non-empty. `baseUrl` (optional) is an OpenAI-compatible LiteLLM API base; when
+ * omitted, the baked LiteLLM gateway is reused and only the runtime API key is set.
  * `model` (optional) selects the model id; when omitted, the session default is
  * kept. The token lives in session/runtime memory only — never written to disk. */
 export interface Configure {

package/src/cli/args.ts

@@ -5,7 +5,6 @@ import { type Effort, THINKING_EFFORTS } from "@f5-sales-demo/pi-ai";
 import { APP_NAME, CONFIG_DIR_NAME, logger } from "@f5-sales-demo/pi-utils";
 import chalk from "chalk";
 import { parseEffort } from "../thinking";
-import { BUILTIN_TOOLS } from "../tools";
 import {
 	flagNameForChar,
 	flagSpec,
@@ -25,6 +24,7 @@ export interface Args {
 	/** Extra directories the session may read AND write, beyond its CWD subtree (repeatable). */
 	allowPath?: string[];
 	provider?: string;
+	context?: string;
 	model?: string;
 	smol?: string;
 	slow?: string;
@@ -39,6 +39,7 @@ export interface Args {
 	version?: boolean;
 	mode?: Mode;
 	noSession?: boolean;
+	noMemories?: boolean;
 	sessionDir?: string;
 	providerSessionId?: string;
 	fork?: string;
@@ -95,6 +96,9 @@ const APPLY: Record<LaunchFlagName, (result: Args, value: string | true) => void
 	provider: (r, v) => {
 		r.provider = v as string;
 	},
+	context: (r, v) => {
+		r.context = v as string;
+	},
 	"api-key": (r, v) => {
 		r.apiKey = v as string;
 	},
@@ -138,6 +142,9 @@ const APPLY: Record<LaunchFlagName, (result: Args, value: string | true) => void
 	"no-session": r => {
 		r.noSession = true;
 	},
+	"no-memories": r => {
+		r.noMemories = true;
+	},
 	"provider-session-id": (r, v) => {
 		r.providerSessionId = v as string;
 	},
@@ -157,22 +164,10 @@ const APPLY: Record<LaunchFlagName, (result: Args, value: string | true) => void
 		r.noPty = true;
 	},
 	tools: (r, v) => {
-		const toolNames = (v as string)
+		r.tools = (v as string)
 			.split(",")
 			.map(s => s.trim().toLowerCase())
 			.filter(Boolean);
-		const validTools: string[] = [];
-		for (const name of toolNames) {
-			if (name in BUILTIN_TOOLS) {
-				validTools.push(name);
-			} else {
-				logger.warn("Unknown tool passed to --tools", {
-					tool: name,
-					validTools: Object.keys(BUILTIN_TOOLS),
-				});
-			}
-		}
-		r.tools = validTools;
 	},
 	thinking: (r, v) => {
 		const thinking = parseEffort(v as string);

package/src/cli/flag-spec.ts

@@ -12,7 +12,7 @@
  * A leaf module on purpose — it imports only the thinking-effort list, so `commands/launch.ts` and
  * `cli/args.ts` can both depend on it without a cycle.
  */
-import { THINKING_EFFORTS } from "@f5-sales-demo/pi-ai";
+import { THINKING_EFFORTS } from "@f5-sales-demo/pi-ai/model-thinking";
 import { CliUsageError, type FlagDescriptor, Flags } from "@f5-sales-demo/pi-utils/cli";
 
 export type FlagArity = "boolean" | "value" | "optional-value" | "repeatable-value";
@@ -46,6 +46,7 @@ export const LAUNCH_FLAGS = defineFlags({
 	slow: { arity: "value", description: "Slow/reasoning model for thorough analysis (or PI_SLOW_MODEL env)" },
 	plan: { arity: "value", description: "Plan model for architectural planning (or PI_PLAN_MODEL env)" },
 	provider: { arity: "value", description: "Provider to use (legacy; prefer --model)" },
+	context: { arity: "value", description: "Bind this session to a named F5 XC context" },
 	"api-key": { arity: "value", description: "API key (defaults to env vars)" },
 	"system-prompt": { arity: "value", description: "System prompt (default: coding assistant prompt)" },
 	"append-system-prompt": { arity: "value", description: "Append text or file contents to the system prompt" },
@@ -74,6 +75,7 @@ export const LAUNCH_FLAGS = defineFlags({
 	fork: { arity: "value", description: "Fork an existing session by ID prefix or path" },
 	"session-dir": { arity: "value", description: "Directory for session storage and lookup" },
 	"no-session": { arity: "boolean", description: "Don't save session (ephemeral)" },
+	"no-memories": { arity: "boolean", description: "Disable project memory loading and maintenance" },
 	"provider-session-id": { arity: "value", description: "Resume a provider-side session", hidden: true },
 	models: { arity: "value", description: "Comma-separated model patterns for Ctrl+P cycling" },
 	"no-tools": { arity: "boolean", description: "Disable all built-in tools" },
@@ -157,6 +159,29 @@ export interface UnrecognizedFlag {
 	name: string;
 }
 
+type ExtensionFlagSpec = ReadonlyMap<string, { type: "boolean" | "string" }>;
+
+function inlineFlag(arg: string): { name: string; value: string } | undefined {
+	const match = /^--([^=]+)=([\s\S]*)$/.exec(arg);
+	if (!match) return undefined;
+	return { name: match[1], value: match[2] };
+}
+
+/** Reject inline values for known boolean flags without loading the agent command. */
+export function validateInlineFlagSyntax(args: readonly string[], extensionFlags?: ExtensionFlagSpec): void {
+	for (const arg of args) {
+		if (arg === "--") return;
+		const inline = inlineFlag(arg);
+		if (!inline) continue;
+
+		const spec = flagSpec(inline.name);
+		const isBoolean = spec?.arity === "boolean" || extensionFlags?.get(inline.name)?.type === "boolean";
+		if (isBoolean) {
+			throw new CliUsageError(`--${inline.name} is a boolean flag and does not take a value`);
+		}
+	}
+}
+
 /**
  * Rewrite `--name=value` into `["--name", "value"]` for every flag that takes a value.
  *
@@ -167,10 +192,8 @@ export interface UnrecognizedFlag {
  *
  * Short forms are untouched: no shell convention makes `-p=x` mean `-p x`.
  */
-export function normalizeFlagTokens(
-	args: readonly string[],
-	extensionFlags?: ReadonlyMap<string, { type: "boolean" | "string" }>,
-): string[] {
+export function normalizeFlagTokens(args: readonly string[], extensionFlags?: ExtensionFlagSpec): string[] {
+	validateInlineFlagSyntax(args, extensionFlags);
 	const normalized: string[] = [];
 	let afterTerminator = false;
 
@@ -185,27 +208,21 @@ export function normalizeFlagTokens(
 			continue;
 		}
 
-		const match = /^--([^=]+)=([\s\S]*)$/.exec(arg);
-		if (!match) {
+		const inline = inlineFlag(arg);
+		if (!inline) {
 			normalized.push(arg);
 			continue;
 		}
 
-		const [, name, value] = match;
+		const { name, value } = inline;
 		const spec = flagSpec(name);
 		if (spec) {
-			if (!takesValue(spec)) {
-				throw new CliUsageError(`--${name} is a boolean flag and does not take a value`);
-			}
 			normalized.push(`--${name}`, value);
 			continue;
 		}
 
 		const extension = extensionFlags?.get(name);
 		if (extension) {
-			if (extension.type === "boolean") {
-				throw new CliUsageError(`--${name} is a boolean flag and does not take a value`);
-			}
 			normalized.push(`--${name}`, value);
 			continue;
 		}

package/src/cli/plugin-cli.ts

@@ -309,6 +309,41 @@ async function handleUpgrade(args: string[], flags: PluginCommandArgs["flags"]):
 	const manager = await makeMarketplaceManager();
 	const pluginId = args[0];
 	try {
+		if (flags.dryRun) {
+			const installed = pluginId
+				? (await manager.listInstalledPlugins()).filter(entry => entry.id === pluginId)
+				: [];
+			if (pluginId && installed.length === 0) {
+				throw new Error(`Plugin "${pluginId}" is not installed`);
+			}
+			if (pluginId && flags.scope && !installed.some(entry => entry.scope === flags.scope)) {
+				throw new Error(`Plugin "${pluginId}" is not installed in ${flags.scope} scope`);
+			}
+
+			const available = await manager.previewPluginUpdates();
+			const updates = available.filter(
+				update =>
+					(pluginId === undefined || update.pluginId === pluginId) &&
+					(flags.scope === undefined || update.scope === flags.scope),
+			);
+			if (flags.json) {
+				process.stdout.write(`${JSON.stringify({ dryRun: true, updates }, null, 2)}\n`);
+			} else if (updates.length === 0) {
+				process.stdout.write(
+					`${pluginId ? `${pluginId} is up to date.` : "All marketplace plugins are up to date."}\n`,
+				);
+			} else {
+				for (const update of updates) {
+					process.stdout.write(
+						`${chalk.dim(
+							`[dry-run] Would upgrade ${update.pluginId} (${update.scope}): ${update.from} -> ${update.to}`,
+						)}\n`,
+					);
+				}
+			}
+			return;
+		}
+
 		if (pluginId) {
 			if (flags.scope) {
 				const result = await manager.upgradePlugin(pluginId, flags.scope, { refresh: true });

package/src/cli/sandbox-check.ts

@@ -13,7 +13,8 @@ import {
 	SANDBOX_OPERATOR_HOME_ENV,
 	SANDBOX_SESSION_ROOT_ENV,
 } from "../sandbox/session-fence";
-import { BashTool, type ToolSession } from "../tools";
+import type { ToolSession } from "../tools";
+import { BashTool } from "../tools/bash";
 
 export type SandboxCheckResultStatus = "PASS" | "FAIL" | "SKIP" | "ERROR";
 

package/src/cli/sandbox-spec.ts

@@ -0,0 +1,22 @@
+import { Args, CliUsageError, Flags } from "@f5-sales-demo/pi-utils/cli";
+import { findCommandLaunchFlags, launchFlagScopeMessage } from "./root-command-routing";
+
+export const sandboxArgs = {
+	action: Args.string({
+		description: "Sandbox action",
+		required: true,
+		options: ["check"],
+	}),
+};
+
+export const sandboxFlags = {
+	json: Flags.boolean({ description: "Output JSON" }),
+	verbose: Flags.boolean({ char: "v", description: "Show failure details" }),
+};
+
+export function validateSandboxInvocation(argv: readonly string[], bin: string): void {
+	const launchFlags = findCommandLaunchFlags(argv, sandboxFlags);
+	if (launchFlags.length > 0) {
+		throw new CliUsageError(launchFlagScopeMessage(launchFlags, "sandbox", argv, bin));
+	}
+}

package/src/cli.ts

@@ -4,8 +4,10 @@ import { APP_NAME, initI18n, MIN_BUN_VERSION, registerLocales, t, VERSION } from
  * CLI entry point — registers all commands explicitly and delegates to the
  * lightweight CLI runner from pi-utils.
  */
-import { type CommandEntry, run } from "@f5-sales-demo/pi-utils/cli";
+import { CliUsageError, type CommandEntry, run } from "@f5-sales-demo/pi-utils/cli";
+import { validateInlineFlagSyntax } from "./cli/flag-spec";
 import { findPrefixedCommand, launchFlagScopeMessage } from "./cli/root-command-routing";
+import { sandboxArgs, sandboxFlags, validateSandboxInvocation } from "./cli/sandbox-spec";
 import { locales } from "./locales/index";
 
 registerLocales(locales);
@@ -57,7 +59,12 @@ const commands: CommandEntry[] = [
 	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
 	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
 	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
-	{ name: "sandbox", load: () => import("./commands/sandbox").then(m => m.default) },
+	{
+		name: "sandbox",
+		load: () => import("./commands/sandbox").then(m => m.default),
+		validate: argv => validateSandboxInvocation(argv, APP_NAME),
+		syntax: { args: sandboxArgs, flags: sandboxFlags },
+	},
 	{ name: "jupyter", load: () => import("./commands/jupyter").then(m => m.default) },
 	{ name: "manager", load: () => import("./commands/manager").then(m => m.default) },
 	{ name: "office", load: () => import("./commands/office").then(m => m.default) },
@@ -103,6 +110,16 @@ export function runCli(argv: string[]): Promise<void> {
 	// --help and --version are handled by run() directly, don't rewrite those.
 	// Everything else that isn't a known subcommand routes to "launch".
 	const first = argv[0];
+	if (!isSubcommand(first)) {
+		try {
+			validateInlineFlagSyntax(argv);
+		} catch (error) {
+			if (!(error instanceof CliUsageError)) throw error;
+			process.stderr.write(`Error: ${error.message}\n`);
+			process.exitCode = 2;
+			return Promise.resolve();
+		}
+	}
 	const prefixedCommand = findPrefixedCommand(argv, token => isSubcommand(token));
 	if (
 		prefixedCommand !== undefined &&