magus-cli 7.11.8 → 7.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.11.8",
+  "version": "7.12.0",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -65,8 +65,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "magus-cli-darwin-arm64": "7.11.8",
-    "magus-cli-darwin-x64": "7.11.8",
-    "magus-cli-linux-x64": "7.11.8"
+    "magus-cli-darwin-arm64": "7.12.0",
+    "magus-cli-darwin-x64": "7.12.0",
+    "magus-cli-linux-x64": "7.12.0"
   }
 }

package/src/__tests__/alias-agent-teams.test.ts

@@ -0,0 +1,259 @@
+import { describe, expect, it } from "bun:test";
+import { ALIAS_FLAGS, FLAG_GROUPS, getFlagById } from "../data/alias-flags";
+import {
+	type ShellKind,
+	parseAliasFromRc,
+	renderAlias,
+	renderArgs,
+	renderArgsAsTokens,
+	renderEnv,
+} from "../services/alias-shell-writer";
+import type { AliasConfig } from "../services/alias-store";
+
+const assignment = "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1";
+const shells: ShellKind[] = ["bash", "zsh", "fish"];
+const modes = ["tmux", "iterm2", "in-process", "auto"];
+
+function expectAliasLine(
+	block: string,
+	shell: ShellKind,
+	envEnabled: boolean,
+	argv: string[],
+	aliasName = "c",
+) {
+	const lines = block.split("\n").filter((line) => line.startsWith("alias "));
+	const prefix = envEnabled
+		? `${(shell === "fish" ? "env " : "") + assignment} claude`
+		: "claude";
+	const bareArgs = argv.length === 0 ? "" : ` ${argv.join(" ")}`;
+
+	expect(lines).toHaveLength(1);
+	if (shell === "fish") {
+		const quotedArgs =
+			argv.length === 0 ? "" : ` ${argv.map((arg) => `'${arg}'`).join(" ")}`;
+		expect([
+			`alias ${aliasName} '${prefix}${bareArgs}'`,
+			`alias ${aliasName} '${prefix}${quotedArgs}'`,
+		]).toContain(lines[0]);
+	} else {
+		expect(lines).toEqual([`alias ${aliasName}='${prefix}${bareArgs}'`]);
+	}
+}
+
+describe("agent teams catalog", () => {
+	it("TEST-7 REQ-1 REQ-4 exposes an env-backed boolean and the Agent teams group", () => {
+		expect(getFlagById("agent-teams")).toMatchObject({
+			id: "agent-teams",
+			label: "Agent teams",
+			kind: "boolean",
+			env: assignment,
+			flag: assignment,
+			group: "agents",
+		});
+		expect(FLAG_GROUPS.filter((group) => group.id === "agents")).toEqual([
+			{ id: "agents", label: "Agent teams" },
+		]);
+		expect(
+			ALIAS_FLAGS.filter((flag) => flag.id === "agent-teams"),
+		).toHaveLength(1);
+	});
+
+	it("TEST-8 REQ-4 exposes exactly the teammate choices and their dependency", () => {
+		const flag = getFlagById("teammate-mode");
+
+		expect(flag).toMatchObject({
+			id: "teammate-mode",
+			label: "Teammate panes",
+			kind: "select",
+			flag: "--teammate-mode",
+			group: "agents",
+			requires: "agent-teams",
+		});
+		expect(flag.options?.map((option) => option.value).sort()).toEqual([
+			"auto",
+			"in-process",
+			"iterm2",
+			"tmux",
+		]);
+		expect(flag.env).toBeUndefined();
+	});
+});
+
+describe("environment and argv separation", () => {
+	for (const state of ["enabled", "disabled", "missing"] as const) {
+		it(`TEST-9 REQ-1 REQ-6 REQ-7 REQ-9 separates env from argv when agent teams is ${state}`, () => {
+			const config: AliasConfig = { aliasName: "c", flags: {} };
+			if (state !== "missing") {
+				config.flags["agent-teams"] = {
+					kind: "boolean",
+					enabled: state === "enabled",
+				};
+			}
+			const expectedEnv = state === "enabled" ? [assignment] : [];
+
+			expect(renderEnv(config)).toEqual(expectedEnv);
+			expect(renderArgs(config)).toEqual([]);
+			expect(renderArgsAsTokens(config)).toEqual(expectedEnv);
+		});
+	}
+});
+
+describe("agent teams shell output and POSIX round-trips", () => {
+	// Fish rendering is covered; the parse-back contract uses POSIX alias lines.
+	for (const shell of shells) {
+		it(`TEST-10 REQ-8 REQ-13 renders agent teams alone before claude on ${shell}`, () => {
+			const config: AliasConfig = {
+				aliasName: "c",
+				flags: { "agent-teams": { kind: "boolean", enabled: true } },
+			};
+
+			const rendered = renderAlias(config, shell);
+
+			expect(rendered.shell).toBe(shell);
+			expectAliasLine(rendered.block, shell, true, []);
+			if (shell !== "fish") {
+				expect(parseAliasFromRc(rendered.block)).toEqual({
+					aliasName: "c",
+					flags: { "agent-teams": { kind: "boolean", enabled: true } },
+				});
+			}
+		});
+
+		for (const mode of modes) {
+			it(`TEST-11 REQ-4 REQ-6 REQ-7 REQ-8 REQ-9 REQ-13 ${shell === "fish" ? "renders " : "renders and round-trips "}${mode} teammates on ${shell}`, () => {
+				const config: AliasConfig = {
+					aliasName: "c",
+					flags: {
+						"agent-teams": { kind: "boolean", enabled: true },
+						"teammate-mode": { kind: "select", enabled: true, value: mode },
+					},
+				};
+
+				const rendered = renderAlias(config, shell);
+
+				expect(renderEnv(config)).toEqual([assignment]);
+				expect(renderArgs(config)).toEqual([
+					{ kind: "literal", text: "--teammate-mode" },
+					{ kind: "literal", text: mode },
+				]);
+				expect(renderArgsAsTokens(config)).toEqual([
+					assignment,
+					"--teammate-mode",
+					mode,
+				]);
+				expectAliasLine(rendered.block, shell, true, ["--teammate-mode", mode]);
+				if (shell !== "fish") {
+					expect(parseAliasFromRc(rendered.block)).toEqual({
+						aliasName: "c",
+						flags: {
+							"agent-teams": { kind: "boolean", enabled: true },
+							"teammate-mode": { kind: "select", enabled: true, value: mode },
+						},
+					});
+				}
+			});
+		}
+
+		for (const state of ["missing", "disabled"] as const) {
+			it(`TEST-12 REQ-14 drops teammate-mode with ${state} agent teams but keeps context size on ${shell}`, () => {
+				const config: AliasConfig = {
+					aliasName: "c",
+					flags: {
+						"teammate-mode": { kind: "select", enabled: true, value: "tmux" },
+						autocompact: { kind: "text", enabled: true, value: "200k" },
+					},
+				};
+				if (state === "disabled") {
+					config.flags["agent-teams"] = { kind: "boolean", enabled: false };
+				}
+				const original = structuredClone(config);
+
+				const rendered = renderAlias(config, shell);
+
+				expect(renderEnv(config)).toEqual([]);
+				expect(renderArgs(config)).toEqual([
+					{ kind: "literal", text: "--autocompact" },
+					{ kind: "literal", text: "200k" },
+				]);
+				expect(renderArgsAsTokens(config)).toEqual(["--autocompact", "200k"]);
+				expectAliasLine(rendered.block, shell, false, [
+					"--autocompact",
+					"200k",
+				]);
+				if (shell !== "fish") {
+					expect(parseAliasFromRc(rendered.block)).toEqual({
+						aliasName: "c",
+						flags: {
+							autocompact: { kind: "text", enabled: true, value: "200k" },
+						},
+					});
+				}
+				expect(config).toEqual(original);
+			});
+		}
+
+		it(`TEST-13 REQ-4 REQ-7 REQ-8 REQ-13 keeps agent teams but omits a disabled teammate mode on ${shell}`, () => {
+			const config: AliasConfig = {
+				aliasName: "c",
+				flags: {
+					"agent-teams": { kind: "boolean", enabled: true },
+					"teammate-mode": { kind: "select", enabled: false, value: "tmux" },
+				},
+			};
+
+			const rendered = renderAlias(config, shell);
+
+			expect(renderArgs(config)).toEqual([]);
+			expect(renderArgsAsTokens(config)).toEqual([assignment]);
+			expectAliasLine(rendered.block, shell, true, []);
+			if (shell !== "fish") {
+				expect(parseAliasFromRc(rendered.block)).toEqual({
+					aliasName: "c",
+					flags: { "agent-teams": { kind: "boolean", enabled: true } },
+				});
+			}
+		});
+
+		it(`TEST-14 REQ-6 REQ-7 REQ-8 REQ-9 REQ-13 renders all new options with env first on ${shell}`, () => {
+			const config: AliasConfig = {
+				aliasName: "crew",
+				flags: {
+					"teammate-mode": { kind: "select", enabled: true, value: "tmux" },
+					autocompact: { kind: "text", enabled: true, value: "200k" },
+					"agent-teams": { kind: "boolean", enabled: true },
+				},
+			};
+			const contextIndex = ALIAS_FLAGS.findIndex(
+				(flag) => flag.id === "autocompact",
+			);
+			const modeIndex = ALIAS_FLAGS.findIndex(
+				(flag) => flag.id === "teammate-mode",
+			);
+			expect(contextIndex).toBeGreaterThanOrEqual(0);
+			expect(modeIndex).toBeGreaterThanOrEqual(0);
+			const argv =
+				contextIndex < modeIndex
+					? ["--autocompact", "200k", "--teammate-mode", "tmux"]
+					: ["--teammate-mode", "tmux", "--autocompact", "200k"];
+
+			const rendered = renderAlias(config, shell);
+
+			expect(renderEnv(config)).toEqual([assignment]);
+			expect(renderArgs(config)).toEqual(
+				argv.map((text) => ({ kind: "literal", text })),
+			);
+			expect(renderArgsAsTokens(config)).toEqual([assignment, ...argv]);
+			expectAliasLine(rendered.block, shell, true, argv, "crew");
+			if (shell !== "fish") {
+				expect(parseAliasFromRc(rendered.block)).toEqual({
+					aliasName: "crew",
+					flags: {
+						"agent-teams": { kind: "boolean", enabled: true },
+						"teammate-mode": { kind: "select", enabled: true, value: "tmux" },
+						autocompact: { kind: "text", enabled: true, value: "200k" },
+					},
+				});
+			}
+		});
+	}
+});

package/src/__tests__/alias-autocompact.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from "bun:test";
+import {
+	AUTOCOMPACT_MAX_TOKENS,
+	AUTOCOMPACT_MIN_TOKENS,
+	getFlagById,
+	parseAutocompactSize,
+	validateAutocompactSize,
+} from "../data/alias-flags";
+import {
+	type ShellKind,
+	parseAliasFromRc,
+	renderAlias,
+	renderArgs,
+	renderArgsAsTokens,
+	renderEnv,
+} from "../services/alias-shell-writer";
+import type { AliasConfig } from "../services/alias-store";
+
+const shells: ShellKind[] = ["bash", "zsh", "fish"];
+
+function expectSizeAlias(block: string, shell: ShellKind, value?: string) {
+	const lines = block.split("\n").filter((line) => line.startsWith("alias "));
+	const args = value === undefined ? "" : ` --autocompact ${value}`;
+
+	expect(lines).toHaveLength(1);
+	if (shell === "fish") {
+		const quotedArgs = value === undefined ? "" : ` '--autocompact' '${value}'`;
+		expect([
+			`alias c 'claude${args}'`,
+			`alias c 'claude${quotedArgs}'`,
+		]).toContain(lines[0]);
+	} else {
+		expect(lines).toEqual([`alias c='claude${args}'`]);
+	}
+}
+
+describe("context window size catalog and validation", () => {
+	it("TEST-1 REQ-2 exposes the context text option and its validator", () => {
+		const flag = getFlagById("autocompact");
+
+		expect(flag).toMatchObject({
+			id: "autocompact",
+			label: "Context window size",
+			kind: "text",
+			flag: "--autocompact",
+			group: "context",
+		});
+		expect(typeof flag.validateValue).toBe("function");
+		expect(flag.env).toBeUndefined();
+	});
+
+	const validSizes: Array<[string, number | "auto"]> = [
+		["auto", "auto"],
+		["AUTO", "auto"],
+		["aUtO", "auto"],
+		["200k", 200000],
+		["1m", 1000000],
+		["200000", 200000],
+		["500", 500000],
+		["100k", 100000],
+		["100000", 100000],
+		["100", 100000],
+		["1000k", 1000000],
+		["1000000", 1000000],
+		["1000", 1000000],
+	];
+
+	for (const [value, expected] of validSizes) {
+		it(`TEST-2 REQ-3 accepts ${JSON.stringify(value)} as ${expected}`, () => {
+			const catalogValidator = getFlagById("autocompact").validateValue;
+
+			expect(parseAutocompactSize(value)).toBe(expected);
+			expect(validateAutocompactSize(value)).toBeNull();
+			expect(catalogValidator?.(value)).toBeNull();
+		});
+	}
+
+	const invalidSizes = [
+		"50k",
+		"2m",
+		"abc",
+		"",
+		"0",
+		"99",
+		"1001",
+		"99k",
+		"1001k",
+		"99999",
+		"1000001",
+	];
+
+	for (const value of invalidSizes) {
+		it(`TEST-3 REQ-3 rejects ${JSON.stringify(value)} with a reason`, () => {
+			const catalogValidator = getFlagById("autocompact").validateValue;
+
+			expect(parseAutocompactSize(value)).toBeUndefined();
+			const reasons = [
+				validateAutocompactSize(value),
+				catalogValidator?.(value),
+			];
+			for (const reason of reasons) {
+				expect(reason).toEqual(expect.any(String));
+				expect(reason).toMatch(/\S/);
+			}
+		});
+	}
+
+	it("TEST-4 REQ-3 exposes the inclusive 100000–1000000 token limits", () => {
+		expect(AUTOCOMPACT_MIN_TOKENS).toBe(100000);
+		expect(AUTOCOMPACT_MAX_TOKENS).toBe(1000000);
+	});
+});
+
+describe("context window size shell output", () => {
+	// Fish rendering is covered; the parse-back contract uses POSIX alias lines.
+	for (const shell of shells) {
+		for (const value of ["auto", "200k", "1m", "200000", "500"]) {
+			it(`TEST-5 REQ-2 REQ-7 REQ-8 REQ-13 ${shell === "fish" ? "renders " : "renders and round-trips "}${value} on ${shell}`, () => {
+				const config: AliasConfig = {
+					aliasName: "c",
+					flags: {
+						autocompact: { kind: "text", enabled: true, value },
+					},
+				};
+
+				const rendered = renderAlias(config, shell);
+
+				expect(rendered.shell).toBe(shell);
+				expect(renderEnv(config)).toEqual([]);
+				expect(renderArgs(config)).toEqual([
+					{ kind: "literal", text: "--autocompact" },
+					{ kind: "literal", text: value },
+				]);
+				expect(renderArgsAsTokens(config)).toEqual(["--autocompact", value]);
+				expectSizeAlias(rendered.block, shell, value);
+				if (shell !== "fish") {
+					expect(parseAliasFromRc(rendered.block)).toEqual({
+						aliasName: "c",
+						flags: {
+							autocompact: { kind: "text", enabled: true, value },
+						},
+					});
+				}
+			});
+		}
+
+		it(`TEST-6 REQ-2 REQ-10 omits a disabled context size on ${shell}`, () => {
+			const config: AliasConfig = {
+				aliasName: "c",
+				flags: {
+					autocompact: { kind: "text", enabled: false, value: "200k" },
+				},
+			};
+
+			const rendered = renderAlias(config, shell);
+
+			expect(renderArgs(config)).toEqual([]);
+			expect(renderArgsAsTokens(config)).toEqual([]);
+			expect(renderEnv(config)).toEqual([]);
+			expectSizeAlias(rendered.block, shell);
+			if (shell !== "fish") {
+				expect(parseAliasFromRc(rendered.block)).toEqual({
+					aliasName: "c",
+					flags: {},
+				});
+			}
+		});
+	}
+});

package/src/__tests__/alias-env-adoption.test.ts

@@ -0,0 +1,334 @@
+import { describe, expect, it } from "bun:test";
+import {
+	argsToFlagValuesWithLeftovers,
+	findAdoptableAlias,
+	parseAliasFromRc,
+	parseAliasLine,
+	parseManagedBlock,
+	renderAlias,
+} from "../services/alias-shell-writer";
+import type { AliasConfig, FlagValue } from "../services/alias-store";
+
+const assignment = "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1";
+
+function combinedFlags(): Record<string, FlagValue> {
+	return {
+		"agent-teams": { kind: "boolean", enabled: true },
+		"teammate-mode": { kind: "select", enabled: true, value: "tmux" },
+		autocompact: { kind: "text", enabled: true, value: "200k" },
+	};
+}
+
+const forms: Array<{
+	name: string;
+	envLauncher: boolean;
+	line: (body: string) => string;
+}> = [
+	{ name: "POSIX", envLauncher: false, line: (body) => `alias crew='${body}'` },
+	// The env launcher is a body form; the parser contract uses POSIX alias lines.
+	{
+		name: "POSIX with env launcher",
+		envLauncher: true,
+		line: (body) => `alias crew='${body}'`,
+	},
+];
+
+function commandBody(
+	envLauncher: boolean,
+	env: string[],
+	argv: string[],
+): string {
+	return [
+		...(envLauncher && env.length > 0 ? ["env"] : []),
+		...env,
+		"claude",
+		...argv,
+	].join(" ");
+}
+
+describe("managed assignment-prefixed alias parsing", () => {
+	const examples = [
+		{
+			name: "POSIX known assignment",
+			line: `alias crew='${assignment} claude --teammate-mode tmux --autocompact 200k'`,
+			args: [assignment, "--teammate-mode", "tmux", "--autocompact", "200k"],
+		},
+		{
+			name: "POSIX alias with env launcher",
+			line: `alias crew='env ${assignment} claude --teammate-mode tmux --autocompact 200k'`,
+			args: [assignment, "--teammate-mode", "tmux", "--autocompact", "200k"],
+		},
+		{
+			name: "POSIX unknown before known assignment",
+			line: `alias crew='EXTRA=keep ${assignment} claude --autocompact 200k'`,
+			args: ["EXTRA=keep", assignment, "--autocompact", "200k"],
+		},
+		{
+			name: "POSIX env launcher with unknown after known assignment",
+			line: `alias crew='env ${assignment} EXTRA=a=b claude --teammate-mode tmux'`,
+			args: [assignment, "EXTRA=a=b", "--teammate-mode", "tmux"],
+		},
+	];
+
+	for (const example of examples) {
+		it(`TEST-15 REQ-11 preserves env-first tokens for ${example.name}`, () => {
+			const block = [
+				"# >>> magus managed alias >>>",
+				example.line,
+				"# <<< magus managed alias <<<",
+				"",
+			].join("\n");
+			const expected = { aliasName: "crew", args: [...example.args] };
+
+			expect(parseAliasLine(example.line)).toEqual(expected);
+			expect(parseManagedBlock(block)).toEqual(expected);
+		});
+	}
+});
+
+describe("assignment mapping and leftovers", () => {
+	const mappingCases: Array<{
+		name: string;
+		args: string[];
+		flags: () => Record<string, FlagValue>;
+		leftovers: string[];
+	}> = [
+		{
+			name: "known assignment and all new argv options",
+			args: [assignment, "--teammate-mode", "tmux", "--autocompact", "200k"],
+			flags: combinedFlags,
+			leftovers: [],
+		},
+		{
+			name: "unknown assignment before the known one",
+			args: [
+				"EXTRA=keep",
+				assignment,
+				"--teammate-mode",
+				"tmux",
+				"--autocompact",
+				"200k",
+			],
+			flags: combinedFlags,
+			leftovers: ["EXTRA=keep"],
+		},
+		{
+			name: "unknown assignments after the known one",
+			args: [
+				assignment,
+				"EMPTY=",
+				"EXTRA=a=b",
+				"--teammate-mode",
+				"tmux",
+				"--autocompact",
+				"200k",
+			],
+			flags: combinedFlags,
+			leftovers: ["EMPTY=", "EXTRA=a=b"],
+		},
+		{
+			name: "known env name with a different value",
+			args: ["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0", "--ide"],
+			flags: () => ({ ide: { kind: "boolean", enabled: true } }),
+			leftovers: ["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0"],
+		},
+	];
+
+	for (const example of mappingCases) {
+		it(`TEST-16 REQ-12 retains every unmatched token for ${example.name}`, () => {
+			const args = [...example.args];
+
+			expect(argsToFlagValuesWithLeftovers(args)).toEqual({
+				flags: example.flags(),
+				leftovers: [...example.leftovers],
+			});
+		});
+	}
+
+	it("TEST-17 REQ-12 keeps an assignment after an argv flag as a leftover rather than enabling teams", () => {
+		const args = ["--ide", assignment];
+
+		expect(argsToFlagValuesWithLeftovers(args)).toEqual({
+			flags: { ide: { kind: "boolean", enabled: true } },
+			leftovers: [assignment],
+		});
+	});
+
+	it("TEST-17 REQ-12 retains an argv assignment without losing an earlier recognized env assignment", () => {
+		const args = [assignment, "--ide", "EXTRA=keep"];
+
+		expect(argsToFlagValuesWithLeftovers(args)).toEqual({
+			flags: {
+				"agent-teams": { kind: "boolean", enabled: true },
+				ide: { kind: "boolean", enabled: true },
+			},
+			leftovers: ["EXTRA=keep"],
+		});
+	});
+
+	it("TEST-17 REQ-12 leaves an assignment used as a text value inside that text flag", () => {
+		const args = ["--append-system-prompt", assignment];
+
+		expect(argsToFlagValuesWithLeftovers(args)).toEqual({
+			flags: {
+				"append-system-prompt": {
+					kind: "text",
+					enabled: true,
+					value: assignment,
+				},
+			},
+			leftovers: [],
+		});
+	});
+});
+
+describe("safe adoption of assignment-prefixed aliases", () => {
+	const losslessCases: Array<{
+		name: string;
+		env: string[];
+		argv: string[];
+		flags: () => Record<string, FlagValue>;
+	}> = [
+		{
+			name: "context size only",
+			env: [],
+			argv: ["--autocompact", "200k"],
+			flags: () => ({
+				autocompact: { kind: "text", enabled: true, value: "200k" },
+			}),
+		},
+		{
+			name: "agent teams only",
+			env: [assignment],
+			argv: [],
+			flags: () => ({
+				"agent-teams": { kind: "boolean", enabled: true },
+			}),
+		},
+		{
+			name: "all new options",
+			env: [assignment],
+			argv: ["--teammate-mode", "tmux", "--autocompact", "200k"],
+			flags: combinedFlags,
+		},
+	];
+
+	const unknownCases: Array<{
+		name: string;
+		env: string[];
+		argv: string[];
+		flags: () => Record<string, FlagValue>;
+		leftovers: string[];
+	}> = [
+		{
+			name: "an unknown assignment alone",
+			env: ["EXTRA=keep"],
+			argv: ["--ide"],
+			flags: () => ({ ide: { kind: "boolean", enabled: true } }),
+			leftovers: ["EXTRA=keep"],
+		},
+		{
+			name: "an empty-valued unknown assignment before known teams",
+			env: ["EMPTY=", assignment],
+			argv: ["--teammate-mode", "tmux", "--autocompact", "200k"],
+			flags: combinedFlags,
+			leftovers: ["EMPTY="],
+		},
+		{
+			name: "an unknown assignment containing another equals sign after known teams",
+			env: [assignment, "EXTRA=a=b"],
+			argv: ["--teammate-mode", "tmux", "--autocompact", "200k"],
+			flags: combinedFlags,
+			leftovers: ["EXTRA=a=b"],
+		},
+		{
+			name: "a known assignment name with an unsupported value",
+			env: ["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0"],
+			argv: ["--ide"],
+			flags: () => ({ ide: { kind: "boolean", enabled: true } }),
+			leftovers: ["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0"],
+		},
+	];
+
+	for (const form of forms) {
+		for (const example of losslessCases) {
+			it(`TEST-18 REQ-11 REQ-13 adopts ${example.name} losslessly in ${form.name}`, () => {
+				const line = form.line(
+					commandBody(form.envLauncher, example.env, example.argv),
+				);
+				const rc = `# personal aliases\n${line}\n# end aliases\n`;
+				const expectedFlags = example.flags();
+
+				const adopted = findAdoptableAlias(rc);
+
+				expect(adopted).toEqual({
+					name: "crew",
+					flags: expectedFlags,
+					lineRange: [1, 1],
+					leftovers: [],
+					lossless: true,
+					rawLine: line,
+					others: [],
+				});
+				if (adopted === null) {
+					throw new Error("Expected a lossless adoptable alias");
+				}
+				const config: AliasConfig = {
+					aliasName: adopted.name,
+					flags: adopted.flags,
+				};
+				expect(parseAliasFromRc(renderAlias(config, "bash").block)).toEqual({
+					aliasName: "crew",
+					flags: expectedFlags,
+				});
+			});
+		}
+
+		for (const example of unknownCases) {
+			it(`TEST-19 REQ-11 REQ-12 REQ-13 preserves ${example.name} as a leftover in ${form.name}`, () => {
+				const line = form.line(
+					commandBody(form.envLauncher, example.env, example.argv),
+				);
+				const rc = `# personal aliases\n${line}\n# end aliases\n`;
+
+				const adopted = findAdoptableAlias(rc);
+
+				expect(adopted).toEqual({
+					name: "crew",
+					flags: example.flags(),
+					lineRange: [1, 1],
+					leftovers: [...example.leftovers],
+					lossless: false,
+					rawLine: line,
+					others: [],
+				});
+			});
+		}
+
+		it(`TEST-20 REQ-13 REQ-14 refuses lossless adoption of orphan teammate-mode in ${form.name}`, () => {
+			const line = form.line("claude --teammate-mode tmux");
+
+			const adopted = findAdoptableAlias(`${line}\n`);
+
+			expect(adopted).toEqual({
+				name: "crew",
+				flags: {
+					"teammate-mode": { kind: "select", enabled: true, value: "tmux" },
+				},
+				lineRange: [0, 0],
+				leftovers: [],
+				lossless: false,
+				rawLine: line,
+				others: [],
+			});
+		});
+
+		it(`TEST-21 REQ-11 rejects an assignment-prefixed non-claude alias in ${form.name}`, () => {
+			const prefix = form.envLauncher ? "env " : "";
+			const line = form.line(`${prefix + assignment} other-command --ide`);
+
+			expect(parseAliasLine(line)).toBeNull();
+			expect(findAdoptableAlias(`${line}\n`)).toBeNull();
+		});
+	}
+});

package/src/__tests__/alias-option-compatibility.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "bun:test";
+import {
+	type ShellKind,
+	renderAlias,
+	renderArgsAsTokens,
+	renderEnv,
+} from "../services/alias-shell-writer";
+import {
+	type AliasConfig,
+	type FlagValue,
+	defaultAliasConfig,
+} from "../services/alias-store";
+
+const shells: ShellKind[] = ["bash", "zsh", "fish"];
+
+describe("alias output when the new options are not enabled", () => {
+	const establishedCases: Array<{
+		name: string;
+		flags: () => Record<string, FlagValue>;
+		tokens: string[];
+		posixLine: string;
+		fishLine: string;
+	}> = [
+		{
+			name: "plain claude alias",
+			flags: () => ({}),
+			tokens: [],
+			posixLine: "alias c='claude'",
+			fishLine: "alias c 'claude'",
+		},
+		{
+			name: "ide-only alias",
+			flags: () => ({ ide: { kind: "boolean", enabled: true } }),
+			tokens: ["--ide"],
+			posixLine: "alias c='claude --ide'",
+			fishLine: "alias c 'claude '--ide''",
+		},
+	];
+
+	for (const shell of shells) {
+		for (const example of establishedCases) {
+			it(`TEST-22 REQ-10 preserves established ${example.name} bytes on ${shell} with absent or disabled new options`, () => {
+				const absent: AliasConfig = {
+					aliasName: "c",
+					flags: example.flags(),
+				};
+				const disabled: AliasConfig = {
+					aliasName: "c",
+					flags: {
+						...example.flags(),
+						autocompact: { kind: "text", enabled: false, value: "200k" },
+						"agent-teams": { kind: "boolean", enabled: false },
+						"teammate-mode": { kind: "select", enabled: false, value: "tmux" },
+					},
+				};
+
+				const absentOutput = renderAlias(absent, shell);
+				const disabledOutput = renderAlias(disabled, shell);
+
+				expect(absentOutput.shell).toBe(shell);
+				expect(disabledOutput).toEqual(absentOutput);
+				expect(
+					absentOutput.block
+						.split("\n")
+						.filter((line) => line.startsWith("alias ")),
+				).toEqual([shell === "fish" ? example.fishLine : example.posixLine]);
+				expect(
+					absentOutput.block.startsWith("# >>> magus managed alias >>>\n"),
+				).toBe(true);
+				expect(
+					absentOutput.block.endsWith("# <<< magus managed alias <<<\n"),
+				).toBe(true);
+				expect(renderEnv(absent)).toEqual([]);
+				expect(renderEnv(disabled)).toEqual([]);
+				expect(renderArgsAsTokens(absent)).toEqual([...example.tokens]);
+				expect(renderArgsAsTokens(disabled)).toEqual([...example.tokens]);
+			});
+		}
+
+		it(`TEST-23 REQ-10 leaves all new options off in the default ${shell} alias`, () => {
+			const config = defaultAliasConfig();
+			const emptyConfig: AliasConfig = { aliasName: "c", flags: {} };
+
+			expect(config.aliasName).toBe("c");
+			expect(renderEnv(config)).toEqual([]);
+			expect(renderArgsAsTokens(config)).toEqual([]);
+			expect(renderAlias(config, shell)).toEqual(
+				renderAlias(emptyConfig, shell),
+			);
+		});
+	}
+});

package/src/data/alias-flags.ts

@@ -72,6 +72,18 @@ export interface AliasFlag {
 	 * token. See `TEMPLATE_TOKENS` for the supported placeholder set.
 	 */
 	templated?: boolean;
+	/**
+	 * Environment assignment (`NAME=VALUE`) the alias sets before `claude`,
+	 * instead of an argv token. Only for `kind: "boolean"`: enabled emits the
+	 * assignment, disabled emits nothing. `flag` carries the same string so
+	 * lookups by `flag` keep working.
+	 */
+	env?: string;
+	/**
+	 * Value check for `kind: "text"` flags, run when the user enters a value.
+	 * Returns null when the value is valid, otherwise the reason it is not.
+	 */
+	validateValue?: (value: string) => string | null;
 	/** UI grouping; rendered as section headers in the list. */
 	group: FlagGroup;
 }
@@ -100,7 +112,8 @@ export type FlagGroup =
 	| "channels"
 	| "debug"
 	| "integration"
-	| "worktree";
+	| "worktree"
+	| "agents";
 
 export const FLAG_GROUPS: Array<{ id: FlagGroup; label: string }> = [
 	{ id: "danger", label: "Permissions" },
@@ -110,8 +123,81 @@ export const FLAG_GROUPS: Array<{ id: FlagGroup; label: string }> = [
 	{ id: "debug", label: "Debug" },
 	{ id: "integration", label: "Integrations" },
 	{ id: "worktree", label: "Worktree" },
+	{ id: "agents", label: "Agent teams" },
 ];
 
+/** Smallest auto-compact window Claude Code accepts, in tokens. */
+export const AUTOCOMPACT_MIN_TOKENS = 100_000;
+/** Largest auto-compact window Claude Code accepts, in tokens. */
+export const AUTOCOMPACT_MAX_TOKENS = 1_000_000;
+
+/** Claude Code's own wording when it refuses an `--autocompact` value. */
+export const AUTOCOMPACT_INVALID_REASON =
+	"It must be 'auto', or between 100k and 1M (e.g. 500k, 200000, or 200 as shorthand)";
+
+const EXPONENT_NUMBER = /^[+-]?(\d+(\.\d*)?|\.\d+)[eE][+-]?\d+$/;
+const GROUPED_DIGITS = /^[+-]?\d{1,3}([_,   ])\d{3}(?:\1\d{3})*$/;
+const DIGIT_SEPARATORS = /[_,   ]/g;
+
+/**
+ * Read an unsuffixed number the way Claude Code does: exponent notation
+ * (`2e5`) when it is an integer, digit groups (`200,000`, `200_000`), and
+ * otherwise `parseInt`, which keeps the leading digits of the string.
+ */
+function parsePlainNumber(text: string): number {
+	if (text.length <= 32) {
+		if (EXPONENT_NUMBER.test(text)) {
+			const n = Number(text);
+			return Number.isInteger(n) ? n : Number.NaN;
+		}
+		if (GROUPED_DIGITS.test(text)) {
+			return Number.parseInt(text.replace(DIGIT_SEPARATORS, ""), 10);
+		}
+	}
+	return Number.parseInt(text, 10);
+}
+
+/**
+ * Parse an `--autocompact` value exactly as Claude Code's option parser does.
+ *
+ * `auto` (any case) stays `"auto"`. A trailing `k` or `m` multiplies by a
+ * thousand or a million; an unsuffixed number from 100 to 1000 is read as
+ * thousands (`200` is 200,000 tokens). The result must fall between
+ * {@link AUTOCOMPACT_MIN_TOKENS} and {@link AUTOCOMPACT_MAX_TOKENS}.
+ *
+ * Returns the token count, `"auto"`, or `undefined` when Claude Code would
+ * refuse the value.
+ */
+export function parseAutocompactSize(
+	value: string,
+): number | "auto" | undefined {
+	if (value.trim().toLowerCase() === "auto") return "auto";
+	const text = value.trim();
+	const suffix = text.slice(-1).toLowerCase();
+	const multiplier =
+		suffix === "m" ? 1_000_000 : suffix === "k" ? 1_000 : undefined;
+	const parsed =
+		multiplier === undefined
+			? parsePlainNumber(text)
+			: Number.parseFloat(text) * multiplier;
+	const tokens =
+		multiplier === undefined && parsed >= 100 && parsed <= 1000
+			? parsed * 1000
+			: parsed;
+	if (Number.isNaN(tokens) || tokens < 1) return undefined;
+	if (tokens < AUTOCOMPACT_MIN_TOKENS || tokens > AUTOCOMPACT_MAX_TOKENS) {
+		return undefined;
+	}
+	return Math.round(tokens);
+}
+
+/** `validateValue` for the context window size: Claude Code's reason, or null. */
+export function validateAutocompactSize(value: string): string | null {
+	return parseAutocompactSize(value) === undefined
+		? AUTOCOMPACT_INVALID_REASON
+		: null;
+}
+
 export const ALIAS_FLAGS: AliasFlag[] = [
 	{
 		id: "dangerously-skip-permissions",
@@ -222,6 +308,16 @@ export const ALIAS_FLAGS: AliasFlag[] = [
 		description:
 			"Path to a file whose contents are appended to the default system prompt.",
 	},
+	{
+		id: "autocompact",
+		label: "Context window size",
+		flag: "--autocompact",
+		kind: "text",
+		group: "context",
+		validateValue: validateAutocompactSize,
+		description:
+			"The window size Claude Code compacts the conversation at: auto, or 100k to 1M tokens (e.g. 200k, 500k, 1m, 200000, or 200 as shorthand for 200k).",
+	},
 	{
 		id: "channels",
 		label: "Channels (approved)",
@@ -291,6 +387,32 @@ export const ALIAS_FLAGS: AliasFlag[] = [
 			{ label: "classic", value: "classic" },
 		],
 	},
+	{
+		id: "agent-teams",
+		label: "Agent teams",
+		flag: "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1",
+		env: "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1",
+		kind: "boolean",
+		group: "agents",
+		description:
+			"Turn on agent teams, so the session can start teammates. Claude Code has no flag for this: the alias sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 before claude.",
+	},
+	{
+		id: "teammate-mode",
+		label: "Teammate panes",
+		flag: "--teammate-mode",
+		kind: "select",
+		group: "agents",
+		requires: "agent-teams",
+		description:
+			"Where teammates run. tmux opens each teammate in a split pane, but only when the session starts inside tmux. iterm2 uses iTerm2 panes, in-process keeps them in this terminal, auto picks for you. Requires agent teams.",
+		options: [
+			{ label: "tmux", value: "tmux" },
+			{ label: "iterm2", value: "iterm2" },
+			{ label: "in-process", value: "in-process" },
+			{ label: "auto", value: "auto" },
+		],
+	},
 ];
 
 /** Look up a flag by id. Throws if missing — keeps callers honest. */

package/src/services/alias-shell-writer.ts

@@ -125,6 +125,8 @@ export function renderArgs(config: AliasConfig): Segment[] {
 	const seenXor = new Set<string>();
 
 	for (const flag of ALIAS_FLAGS) {
+		// Env flags are assignments before `claude`, never argv: see renderEnv.
+		if (flag.env) continue;
 		if (flag.requires) {
 			const dep = config.flags[flag.requires];
 			if (!isFlagEnabled(dep)) continue;
@@ -154,18 +156,35 @@ export function renderArgs(config: AliasConfig): Segment[] {
 }
 
 /**
- * Convenience: render each segment to its literal-token approximation.
- * Composite segments are stringified by joining their literal parts with
- * `<sub>` placeholders for raw parts. Used by tests and validation summaries
- * where the actual shell substitution doesn't matter.
+ * The environment assignments (`NAME=VALUE`) the alias sets before `claude`,
+ * one per enabled env flag, in catalog order. `requires` applies here as it
+ * does to argv flags. Pure function.
+ */
+export function renderEnv(config: AliasConfig): string[] {
+	const out: string[] = [];
+	for (const flag of ALIAS_FLAGS) {
+		if (!flag.env) continue;
+		if (flag.requires && !isFlagEnabled(config.flags[flag.requires])) continue;
+		if (isFlagEnabled(config.flags[flag.id])) out.push(flag.env);
+	}
+	return out;
+}
+
+/**
+ * Convenience: the whole command after the alias name as literal tokens, env
+ * assignments first, then argv. Composite segments are stringified by joining
+ * their literal parts with `<sub>` placeholders for raw parts. Used by the
+ * adoption fixpoint check, tests and validation summaries, where the actual
+ * shell substitution doesn't matter.
  */
 export function renderArgsAsTokens(config: AliasConfig): string[] {
-	return renderArgs(config).map((seg) => {
+	const argv = renderArgs(config).map((seg) => {
 		if (seg.kind === "literal") return seg.text;
 		return seg.parts
 			.map((p) => (p.kind === "literal" ? p.text : `<${p.posix}>`))
 			.join("");
 	});
+	return [...renderEnv(config), ...argv];
 }
 
 function isFlagEnabled(value: FlagValue | undefined): boolean {
@@ -345,24 +364,32 @@ export function renderAlias(
 	shell: ShellKind,
 ): RenderedAlias {
 	const args = renderArgs(config);
+	const env = renderEnv(config);
 	const name = config.aliasName;
 	if (shell === "fish") {
-		return { shell, block: renderFishBlock(name, args) };
+		return { shell, block: renderFishBlock(name, env, args) };
 	}
-	return { shell, block: renderPosixBlock(name, args) };
+	return { shell, block: renderPosixBlock(name, env, args) };
 }
 
-function renderPosixBlock(name: string, segments: Segment[]): string {
+function renderPosixBlock(
+	name: string,
+	env: string[],
+	segments: Segment[],
+): string {
 	// The alias body lives inside outer single quotes:
-	//   alias <name>='claude … '
-	// Each segment becomes one shell-arg inside that body. Composite segments
+	//   alias <name>='NAME=VALUE claude … '
+	// Env assignments lead, so the shell exports them to `claude` alone. Each
+	// segment becomes one shell-arg inside that body. Composite segments
 	// (templated values) interleave literal text with double-quoted shell
 	// substitutions via close-outer + double-quote + reopen-outer.
+	const prefix =
+		env.length === 0 ? "" : `${env.map(quoteInsidePosixAlias).join(" ")} `;
 	const body =
 		segments.length === 0
 			? ""
 			: ` ${segments.map(renderPosixSegment).join(" ")}`;
-	const line = `alias ${name}='claude${body}'`;
+	const line = `alias ${name}='${prefix}claude${body}'`;
 	return `${BLOCK_BEGIN}\n${line}\n${BLOCK_END}\n`;
 }
 
@@ -425,13 +452,22 @@ export function findUnquotableTokens(segments: Segment[]): string[] {
 	return out;
 }
 
-function renderFishBlock(name: string, segments: Segment[]): string {
+function renderFishBlock(
+	name: string,
+	env: string[],
+	segments: Segment[],
+): string {
 	// Fish: `alias <name> 'claude --foo bar'` — outer single quotes, no `=`.
+	// Env assignments go through `env NAME=VALUE claude …`: the bare
+	// `NAME=VALUE cmd` form needs fish 3.1, `env` works on every version. The
+	// assignments are catalog constants of `[A-Za-z0-9_=]`, so they need no
+	// quoting inside the outer single quotes.
+	const prefix = env.length === 0 ? "" : `env ${env.join(" ")} `;
 	const body =
 		segments.length === 0
 			? ""
 			: ` ${segments.map(renderFishSegment).join(" ")}`;
-	const line = `alias ${name} 'claude${body}'`;
+	const line = `alias ${name} '${prefix}claude${body}'`;
 	return `${BLOCK_BEGIN}\n${line}\n${BLOCK_END}\n`;
 }
 
@@ -604,9 +640,33 @@ export function validateConfig(config: AliasConfig): FlagValidationIssue[] {
 
 export interface ParseResult {
 	aliasName: string | null;
+	/**
+	 * The env assignments before `claude` (`NAME=VALUE`), then the argv after
+	 * it — the shape {@link argsToFlagValuesWithLeftovers} reads.
+	 */
 	args: string[];
 }
 
+/** A shell environment assignment token: `NAME=VALUE`. */
+const ENV_ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/**
+ * Split an alias command into the tokens {@link argsToFlagValuesWithLeftovers}
+ * reads: leading env assignments, then the argv after `claude`. Accepts the
+ * POSIX `NAME=VALUE claude …` form and the `env NAME=VALUE claude …` form the
+ * fish renderer writes. Returns null when the command is not `claude`.
+ */
+function commandTokensAfterEnv(tokens: string[]): string[] | null {
+	let i = tokens[0] === "env" ? 1 : 0;
+	const env: string[] = [];
+	while (i < tokens.length && ENV_ASSIGNMENT_RE.test(tokens[i])) {
+		env.push(tokens[i]);
+		i += 1;
+	}
+	if (tokens[i] !== "claude") return null;
+	return [...env, ...tokens.slice(i + 1)];
+}
+
 /**
  * Find the managed block in shell rc text, parse the alias line, and return
  * the alias name plus the argv tokens after `claude`.
@@ -644,10 +704,11 @@ export function parseAliasLine(line: string): ParseResult | null {
 	const match = ALIAS_LINE_RE.exec(line);
 	if (!match) return null;
 	const [, aliasName, body] = match;
-	// First token is the command itself (claude). Drop it; we only want argv.
-	const tokens = tokenizePosixAliasBody(body);
-	if (tokens.length === 0 || tokens[0] !== "claude") return null;
-	return { aliasName, args: tokens.slice(1) };
+	// The command is `claude`, optionally preceded by env assignments. Drop
+	// `claude` itself; keep the assignments ahead of the argv.
+	const args = commandTokensAfterEnv(tokenizePosixAliasBody(body));
+	if (!args) return null;
+	return { aliasName, args };
 }
 
 /**
@@ -793,13 +854,25 @@ export interface ParsedFlagsWithLeftovers {
  * catalog flag. Unknown `--flag value` pairs contribute BOTH tokens to
  * `leftovers` (the flag and its consumed value) so the adoption gate sees the
  * full extent of what wouldn't round-trip.
+ *
+ * Leading `NAME=VALUE` tokens are the env assignments set before `claude`.
+ * Each matches an env flag by its assignment string; an assignment the
+ * catalog does not know lands in `leftovers` on its own, so adoption never
+ * removes a line it cannot reproduce. Env flags are matched only in that
+ * leading run, never among the argv after it.
  */
 export function argsToFlagValuesWithLeftovers(
 	args: string[],
 ): ParsedFlagsWithLeftovers {
-	// Index every flag by its primary `flag` string AND its triStateOff variant.
+	// Index argv flags by their primary `flag` string AND their triStateOff
+	// variant, and env flags by their assignment string.
 	const byFlag = new Map<string, { flag: AliasFlag; off?: boolean }>();
+	const byEnv = new Map<string, AliasFlag>();
 	for (const flag of ALIAS_FLAGS) {
+		if (flag.env) {
+			byEnv.set(flag.env, flag);
+			continue;
+		}
 		byFlag.set(flag.flag, { flag, off: false });
 		if (flag.triStateOff) {
 			byFlag.set(flag.triStateOff, { flag, off: true });
@@ -809,6 +882,12 @@ export function argsToFlagValuesWithLeftovers(
 	const out: Record<string, FlagValue> = {};
 	const leftovers: string[] = [];
 	let i = 0;
+	while (i < args.length && ENV_ASSIGNMENT_RE.test(args[i])) {
+		const envFlag = byEnv.get(args[i]);
+		if (envFlag) out[envFlag.id] = { kind: "boolean", enabled: true };
+		else leftovers.push(args[i]);
+		i += 1;
+	}
 	while (i < args.length) {
 		const tok = args[i];
 		const entry = byFlag.get(tok);
@@ -1122,9 +1201,9 @@ function parseAdoptableLine(
 	if (!match) return null;
 	const [, name, , body] = match;
 	const tokens = tokenizeGeneralAliasBody(body);
-	if (!tokens || tokens.length === 0 || tokens[0] !== "claude") return null;
-
-	const args = tokens.slice(1);
+	if (!tokens) return null;
+	const args = commandTokensAfterEnv(tokens);
+	if (!args) return null;
 	const { flags, leftovers } = argsToFlagValuesWithLeftovers(args);
 
 	// Fixpoint: render the parsed flags back to tokens and re-parse. If the

package/src/ui/screens/AliasScreen.tsx

@@ -7,6 +7,7 @@ import {
 	ALIAS_FLAGS,
 	type AliasFlag,
 	FLAG_GROUPS,
+	getFlagById,
 } from "../../data/alias-flags.js";
 import { loadAliasName, saveAliasName } from "../../services/alias-settings.js";
 import {
@@ -18,6 +19,7 @@ import {
 	findAdoptableAlias,
 	parseAliasFromRc,
 	renderArgs,
+	renderEnv,
 	validateConfig,
 	writeAliasToShell,
 } from "../../services/alias-shell-writer.js";
@@ -521,9 +523,10 @@ export function AliasScreen() {
 			selectedRow.flag,
 			selectedRow.value,
 			modal,
+			showFailures,
 		);
 		if (next) updateFlag(selectedRow.flag.id, next);
-	}, [selectedRow, modal, updateFlag, editAliasName]);
+	}, [selectedRow, modal, showFailures, updateFlag, editAliasName]);
 
 	const toggleSelected = useCallback(async () => {
 		if (!selectedRow) return;
@@ -680,6 +683,7 @@ export function AliasScreen() {
 
 	// ── Render ────────────────────────────────────────────────────────────
 	const previewSegments = config ? renderArgs(config) : [];
+	const previewEnv = config ? renderEnv(config) : [];
 	const previewAliasName = config?.aliasName ?? "";
 
 	// Native OpenTUI scrollboxes own the scroll math. We render every item
@@ -767,6 +771,7 @@ export function AliasScreen() {
 		selectedRow,
 		isGated,
 		previewAliasName,
+		previewEnv,
 		previewSegments,
 	);
 	// When editing --channels and there are derived rows, the right pane carries
@@ -795,6 +800,7 @@ export function AliasScreen() {
 				detailFlag,
 				detailValue,
 				previewAliasName,
+				previewEnv,
 				previewSegments,
 				derivedNote,
 				stateOverride,
@@ -1081,6 +1087,7 @@ async function editFlagValue(
 	flag: AliasFlag,
 	value: FlagValue,
 	modal: ReturnType<typeof useModal>,
+	showFailures: ReturnType<typeof useFailurePopup>,
 ): Promise<FlagValue | null> {
 	switch (value.kind) {
 		case "boolean":
@@ -1154,6 +1161,17 @@ async function editFlagValue(
 			}
 			const v = await modal.input(flag.label, flag.description, value.value);
 			if (v === null) return null;
+			// An empty value disables the flag, so only a non-empty one is checked.
+			// A refused value leaves the old one in place.
+			const reason = v.length > 0 ? (flag.validateValue?.(v) ?? null) : null;
+			if (reason) {
+				await showFailures(
+					failureReport(`The ${flag.label.toLowerCase()} was not changed`, [
+						{ subject: v, reason },
+					]),
+				);
+				return null;
+			}
 			return { kind: "text", enabled: v.length > 0, value: v };
 		}
 
@@ -1336,6 +1354,7 @@ function renderDetail(
 	row: Row | undefined,
 	isGated: (f: AliasFlag) => boolean,
 	aliasName: string,
+	env: string[],
 	segments: Segment[],
 ): React.ReactNode {
 	if (!row) {
@@ -1357,7 +1376,7 @@ function renderDetail(
 			{headerAndBody}
 			<text fg={theme.colors.text}> </text>
 			<text fg={theme.colors.muted}>Preview:</text>
-			{renderPreviewLines(aliasName, segments)}
+			{renderPreviewLines(aliasName, env, segments)}
 		</box>
 	);
 }
@@ -1407,7 +1426,7 @@ function renderFlagDetail(
 			</text>
 			{gated && (
 				<text fg={theme.colors.muted}>
-					{`Depends on --${row.flag.requires}. Enabling this will turn that on too.`}
+					{`Depends on ${getFlagById(row.flag.requires ?? "").flag}. Enabling this will turn that on too.`}
 				</text>
 			)}
 			{row.issue && (
@@ -1438,18 +1457,23 @@ function renderFlagDetail(
  */
 function renderPreviewLines(
 	aliasName: string,
+	env: string[],
 	segments: Segment[],
 ): React.ReactNode {
+	// Env assignments run before `claude`, so they sit on the head line.
+	const command = [...env, "claude"].join(" ");
 	if (segments.length === 0) {
 		return (
-			<text fg={theme.colors.text}>{`alias ${aliasName || "?"}='claude'`}</text>
+			<text
+				fg={theme.colors.text}
+			>{`alias ${aliasName || "?"}='${command}'`}</text>
 		);
 	}
 	const lines: React.ReactNode[] = [
 		<text
 			key="head"
 			fg={theme.colors.text}
-		>{`alias ${aliasName || "?"}='claude`}</text>,
+		>{`alias ${aliasName || "?"}='${command}`}</text>,
 	];
 	segments.forEach((seg, i) => {
 		lines.push(
@@ -1530,6 +1554,7 @@ function renderFlagDetailRightPane(
 	flag: AliasFlag,
 	value: FlagValue,
 	aliasName: string,
+	env: string[],
 	segments: Segment[],
 	derivedNote?: string,
 	stateOverride?: string,
@@ -1555,7 +1580,7 @@ function renderFlagDetailRightPane(
 			</text>
 			<text fg={theme.colors.text}> </text>
 			<text fg={theme.colors.muted}>Preview:</text>
-			{renderPreviewLines(aliasName, segments)}
+			{renderPreviewLines(aliasName, env, segments)}
 			<text fg={theme.colors.text}> </text>
 			<text fg={theme.colors.muted}>Keys:</text>
 			<text fg={theme.colors.text}>