Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

refactor(cli): extract parseArgs's token rule as classifyPassthroughTokens

Jack Rudenkod4179ed573a6
diff --git a/packages/cli/src/cli-passthrough-walker.test.ts b/packages/cli/src/cli-passthrough-walker.test.ts
new file mode 100644
index 00000000..c4b4423e
--- /dev/null
+++ b/packages/cli/src/cli-passthrough-walker.test.ts
@@ -0,0 +1,175 @@
+/**
+ * `classifyPassthroughTokens` is a second statement of `parseArgs`'s token rule, kept
+ * because the MCP server must judge `claude_flags` without running `parseArgs` (which
+ * prints, exits and reads config). Two statements of one rule drift unless something
+ * runs both: this file does, on one table of inputs, and also scans `parseArgs`'s
+ * source so a flag added there without an arity here fails loudly.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+ CLAUDISH_EXITING_FLAGS,
+ CLAUDISH_FLAG_ARITY,
+ CLAUDISH_INLINE_VALUE_FLAGS,
+ classifyPassthroughTokens,
+ parseArgs,
+} from "./cli.js";
+
+/**
+ * Inputs `parseArgs` can run without exiting, printing or changing global state:
+ * no exiting flag, no recovery switch (a process-wide override), no `--monitor`/
+ * `--advisor` (which edit `process.env`), and `-v` only where the result is
+ * interactive (print mode appends a forwarded `--verbose`).
+ */
+const CASES: Array<{ name: string; argv: string[] }> = [
+ { name: "nothing", argv: [] },
+ {
+ name: "our own argv shape",
+ argv: ["-i", "--model", "x@y", "-y", "--quiet", "--session-id", "u-1", "--add-dir", "/t"],
+ },
+ { name: "unknown flag with a value", argv: ["--agent", "detective"] },
+ { name: "unknown flag with no value", argv: ["--no-session-persistence"] },
+ { name: "comma list, one value", argv: ["--allowedTools", "Read,Bash"] },
+ { name: "space list, a positional slips in", argv: ["--allowedTools", "Read", "Bash"] },
+ { name: "separator then flags", argv: ["--", "--effort", "high"] },
+ { name: "separator alone", argv: ["--"] },
+ { name: "positional prompt", argv: ["--model", "x", "hello world"] },
+ {
+ name: "value that looks like a flag is not consumed by a passthrough flag",
+ argv: ["--system-prompt", "-be terse"],
+ },
+ {
+ name: "claudish value flag consumes a dash-led value",
+ argv: ["--model-opus", "-weird", "--agent", "a"],
+ },
+ {
+ name: "optional value present",
+ argv: ["--default-provider", "openrouter", "--effort", "high"],
+ },
+ { name: "optional value absent", argv: ["--default-provider", "--effort", "high"] },
+ {
+ name: "inline value forms",
+ argv: ["--default-provider=or", "--op-env=env1", "--effort", "low"],
+ },
+ { name: "value-if-any with no value falls through", argv: ["--agent", "a", "--log-diag"] },
+ { name: "value-if-any consumes a dash-led value", argv: ["--log-diag", "-x"] },
+ { name: "bare --resume is the picker", argv: ["--resume", "--agent", "a"] },
+ { name: "--resume with an id is forwarded", argv: ["--resume", "abc-123"] },
+ { name: "verbose stays claudish's in interactive mode", argv: ["-v", "--effort", "high"] },
+ { name: "print flag passes through", argv: ["-p", "hello"] },
+ {
+ name: "team flag consumes its list",
+ argv: ["--team", "a,b", "--mode", "json", "--keep", "go"],
+ },
+ { name: "file flag", argv: ["-f", "prompt.md", "--agent", "a"] },
+ {
+ name: "ports, profiles, levels",
+ argv: [
+ "--port",
+ "4567",
+ "--profile",
+ "p",
+ "--log-level",
+ "minimal",
+ "--effort-override",
+ "high",
+ ],
+ },
+ {
+ name: "flags with values and a trailing positional",
+ argv: ["--effort", "high", "--permission-mode", "plan", "do it"],
+ },
+];
+
+describe("classifyPassthroughTokens ≡ parseArgs", () => {
+ for (const { name, argv } of CASES) {
+ test(name, async () => {
+ const config = await parseArgs([...argv]);
+ const walked = classifyPassthroughTokens(argv);
+ expect(walked.passthrough).toEqual(config.claudeArgs);
+ expect(walked.positionals.length > 0).toBe(Boolean(config._hasPositionalPrompt));
+ const picker = walked.tokens.some(
+ (t) => t.token === "--resume" && t.kind === "claudish-flag"
+ );
+ expect(picker).toBe(Boolean(config._resumePicker));
+ });
+ }
+});
+
+describe("classifyPassthroughTokens names the dangerous inputs", () => {
+ test("`--allowedTools Read Bash` leaves `Bash` positional", () => {
+ expect(classifyPassthroughTokens(["--allowedTools", "Read", "Bash"]).positionals).toEqual([
+ "Bash",
+ ]);
+ });
+
+ test("`-- --effort high` is a separator followed by positionals", () => {
+ const walked = classifyPassthroughTokens(["--", "--effort", "high"]);
+ expect(walked.separatorAt).toBe(0);
+ expect(walked.positionals).toEqual(["--effort", "high"]);
+ });
+
+ test("claudish's own value is never a positional, even when dash-led", () => {
+ const walked = classifyPassthroughTokens(["--model", "-x"]);
+ expect(walked.positionals).toEqual([]);
+ expect(walked.tokens.map((t) => t.kind)).toEqual(["claudish-flag", "claudish-value"]);
+ });
+
+ test("an exiting flag's values are consumed too", () => {
+ const walked = classifyPassthroughTokens(["--probe", "a", "b", "--agent", "x"]);
+ expect(walked.tokens.map((t) => t.kind)).toEqual([
+ "claudish-flag",
+ "claudish-value",
+ "claudish-value",
+ "passthrough-flag",
+ "passthrough-value",
+ ]);
+ });
+});
+
+describe("the arity table covers every flag parseArgs matches", () => {
+ const source = readFileSync(resolve(import.meta.dir, "cli.ts"), "utf8");
+ const start = source.indexOf("export async function parseArgs(");
+ const end = source.indexOf("\n}\n", start);
+ // Comments mention flags that are NOT matched (`--effort` is Claude Code's), so strip them.
+ const body = source
+ .slice(start, end)
+ .replace(/\/\*[\s\S]*?\*\//g, "")
+ .replace(/^\s*\/\/.*$/gm, "");
+ const exact = new Set([...body.matchAll(/arg === "([^"]+)"/g)].map((m) => m[1] as string));
+ const inline = new Set(
+ [...body.matchAll(/arg\.startsWith\("(--[^"=]+)="\)/g)].map((m) => m[1] as string)
+ );
+
+ test("the scan found the parser", () => {
+ expect(start).toBeGreaterThan(-1);
+ expect(exact.size).toBeGreaterThan(40);
+ });
+
+ // `--` and `--resume` are rules of their own; `-p`/`--print` are Claude Code's flags,
+ // which the catch-all forwards and only NOTES (`_hasPrintFlag`).
+ const notClaudishFlags = new Set(["--", "--resume", "-p", "--print"]);
+
+ test("every exact flag in parseArgs has an arity", () => {
+ const missing = [...exact].filter(
+ (f) => !notClaudishFlags.has(f) && !Object.hasOwn(CLAUDISH_FLAG_ARITY, f)
+ );
+ expect(missing).toEqual([]);
+ });
+
+ test("no arity is listed for a flag parseArgs no longer matches", () => {
+ const stale = Object.keys(CLAUDISH_FLAG_ARITY).filter((f) => !exact.has(f));
+ expect(stale).toEqual([]);
+ });
+
+ test("the inline `--flag=value` forms match parseArgs", () => {
+ expect([...inline].sort()).toEqual([...CLAUDISH_INLINE_VALUE_FLAGS].sort());
+ });
+
+ test("every exiting flag is a known flag", () => {
+ for (const f of CLAUDISH_EXITING_FLAGS)
+ expect(Object.hasOwn(CLAUDISH_FLAG_ARITY, f)).toBe(true);
+ });
+});
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index b2b6adfe..f54f4514 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -185,6 +185,274 @@ export function parseAdvisorFlag(value: string): {
};
}
+// ─── The passthrough token rule, as a pure function ──────────────────────────
+//
+// `parseArgs` decides, token by token, what is claudish's own flag, what is a value,
+// what is forwarded to Claude Code, and what is a positional PROMPT. That last class
+// is the dangerous one for a caller that builds an argv for an interactive child: a
+// positional token makes claudish run print mode (`-p`), so `--allowedTools Read Bash`
+// — two values for one flag — silently becomes a one-shot run with the prompt "Bash".
+//
+// `classifyPassthroughTokens` states the same rule without running anything, so the MCP
+// server can refuse such `claude_flags` before a spawn. `cli-passthrough-walker.test.ts`
+// runs both on one table of inputs and scans `parseArgs`'s source for every flag it
+// matches, so the two cannot drift.
+
+/**
+ * How many tokens one of claudish's own flags consumes, as `parseArgs` implements it:
+ *
+ * - `none` — the flag alone.
+ * - `value` — the next token, whatever it looks like (`args[++i]`).
+ * - `value-if-any`— the next token when one exists; with none, `parseArgs` does not
+ * match the flag at all and forwards it to Claude Code.
+ * - `optional` — the next token when it does not start with `-`.
+ * - `query` — the next token when it does not start with `--`.
+ * - `variadic` — every following token up to the next one starting with `--`.
+ *
+ * The flags in `CLAUDISH_EXITING_FLAGS` end the process inside `parseArgs` (they print
+ * and exit), so they are never compared against it; they are listed so the walker
+ * still consumes their values correctly.
+ */
+export type ClaudishFlagArity =
+ | "none"
+ | "value"
+ | "value-if-any"
+ | "optional"
+ | "query"
+ | "variadic";
+
+export const CLAUDISH_FLAG_ARITY: Readonly<Record<string, ClaudishFlagArity>> = {
+ "--model": "value",
+ "-m": "value",
+ "--model-opus": "value",
+ "--model-sonnet": "value",
+ "--model-haiku": "value",
+ "--model-subagent": "value",
+ "--port": "value",
+ "--auto-approve": "none",
+ "-y": "none",
+ "--no-auto-approve": "none",
+ "--dangerous": "none",
+ "--interactive": "none",
+ "-i": "none",
+ "--debug-claudish": "none",
+ "-d": "none",
+ "--recovery-ui": "none",
+ "--no-recovery-ui": "none",
+ "--recovery": "none",
+ "--no-recovery": "none",
+ "--no-debug-claudish": "none",
+ "--log-debug": "none",
+ "--log-level": "value",
+ "--quiet": "none",
+ "-q": "none",
+ "--verbose": "none",
+ "-v": "none",
+ "--json": "none",
+ "--monitor": "none",
+ "--advisor": "value",
+ "--stdin": "none",
+ "--free": "none",
+ "--models-refresh": "none",
+ "--models-skip-update": "none",
+ "--profile": "value",
+ "--default-provider": "optional",
+ "--anthropic-api-billing": "none",
+ "--classifier-model": "value",
+ "--classifier-provider": "value",
+ "--model-params": "value",
+ "--effort-override": "value",
+ "--pro-on-ultracode": "none",
+ "--no-pro-on-ultracode": "none",
+ "--op-env": "value",
+ "--op": "value",
+ "--cost-track": "none",
+ "--cost-audit": "none",
+ "--cost-reset": "none",
+ "--version": "none",
+ "--help": "none",
+ "-h": "none",
+ "--help-ai": "none",
+ "--init": "none",
+ "--probe": "variadic",
+ "--models-top": "none",
+ "--providers": "none",
+ "--models": "query",
+ "-s": "query",
+ "--models-search": "query",
+ "--summarize-tools": "none",
+ "--log-off": "none",
+ "--log-diag": "value-if-any",
+ "--team": "value-if-any",
+ "--mode": "value-if-any",
+ "--keep": "none",
+ "-f": "value-if-any",
+ "--file": "value-if-any",
+};
+
+/** Flags `parseArgs` also accepts in `--flag=value` form, consuming nothing more. */
+export const CLAUDISH_INLINE_VALUE_FLAGS = ["--default-provider", "--op-env", "--op"] as const;
+
+/** Flags whose branch in `parseArgs` prints and exits, so no comparison can reach past them. */
+export const CLAUDISH_EXITING_FLAGS = [
+ "--log-debug",
+ "--version",
+ "--help",
+ "-h",
+ "--help-ai",
+ "--init",
+ "--probe",
+ "--models-top",
+ "--providers",
+ "--models",
+ "-s",
+ "--models-search",
+] as const;
+
+/**
+ * The value rule for a flag claudish does not know: it consumes the next token iff
+ * that token exists and does not start with `-`. Shared by `parseArgs` and the walker.
+ */
+export function passthroughFlagTakesValue(next: string | undefined): boolean {
+ return next !== undefined && !next.startsWith("-");
+}
+
+export type PassthroughTokenKind =
+ | "claudish-flag"
+ | "claudish-value"
+ | "passthrough-flag"
+ | "passthrough-value"
+ | "separator"
+ | "positional";
+
+export interface ClassifiedToken {
+ index: number;
+ token: string;
+ kind: PassthroughTokenKind;
+}
+
+export interface PassthroughClassification {
+ tokens: ClassifiedToken[];
+ /** Every positional token, including all tokens after a `--` separator. */
+ positionals: string[];
+ /** What `parseArgs` forwards to Claude Code, in order (its `claudeArgs`). */
+ passthrough: string[];
+ /** Index of a `--` separator, or null. */
+ separatorAt: number | null;
+}
+
+/** How many tokens after index `i` one of claudish's own flags consumes. */
+function claudishValueCount(
+ arity: ClaudishFlagArity,
+ tokens: readonly string[],
+ i: number
+): number {
+ const next = tokens[i + 1];
+ switch (arity) {
+ case "value":
+ case "value-if-any":
+ return next === undefined ? 0 : 1;
+ case "optional":
+ return passthroughFlagTakesValue(next) ? 1 : 0;
+ case "query":
+ return next && !next.startsWith("--") ? 1 : 0;
+ case "variadic": {
+ let n = 0;
+ while (i + 1 + n < tokens.length && !(tokens[i + 1 + n] as string).startsWith("--")) n++;
+ return n;
+ }
+ default:
+ return 0;
+ }
+}
+
+/**
+ * The arity `parseArgs` applies to `arg` with `next` following, or undefined when it
+ * forwards `arg` to Claude Code. A bare `--resume` (no id) is claudish's session picker.
+ */
+function claudishArityFor(arg: string, next: string | undefined): ClaudishFlagArity | undefined {
+ if (CLAUDISH_INLINE_VALUE_FLAGS.some((f) => arg.startsWith(`${f}=`))) return "none";
+ if (arg === "--resume") return next === undefined || next.startsWith("-") ? "none" : undefined;
+ if (!Object.hasOwn(CLAUDISH_FLAG_ARITY, arg)) return undefined;
+ const arity = CLAUDISH_FLAG_ARITY[arg] as ClaudishFlagArity;
+ // `parseArgs` matches these only when a value follows; alone, they fall through.
+ return arity === "value-if-any" && next === undefined ? undefined : arity;
+}
+
+/**
+ * Classify the token at `i` and any values it consumes. Returns the index of the next
+ * unclassified token, or -1 when `tokens[i]` is a `--` separator.
+ */
+function classifyStep(
+ tokens: readonly string[],
+ i: number,
+ push: (index: number, kind: PassthroughTokenKind) => void
+): number {
+ const arg = tokens[i] as string;
+ const next = tokens[i + 1];
+ const arity = claudishArityFor(arg, next);
+ if (arity !== undefined) {
+ push(i, "claudish-flag");
+ const n = claudishValueCount(arity, tokens, i);
+ for (let k = 1; k <= n; k++) push(i + k, "claudish-value");
+ return i + n + 1;
+ }
+ if (arg === "--") return -1;
+ if (!arg.startsWith("-")) {
+ push(i, "positional");
+ return i + 1;
+ }
+ push(i, "passthrough-flag");
+ if (!passthroughFlagTakesValue(next)) return i + 1;
+ push(i + 1, "passthrough-value");
+ return i + 2;
+}
+
+function summarizeClassification(
+ tokens: ClassifiedToken[],
+ separatorAt: number | null
+): PassthroughClassification {
+ const forwarded = new Set<PassthroughTokenKind>([
+ "passthrough-flag",
+ "passthrough-value",
+ "positional",
+ ]);
+ return {
+ tokens,
+ positionals: tokens.filter((t) => t.kind === "positional").map((t) => t.token),
+ passthrough: tokens.filter((t) => forwarded.has(t.kind)).map((t) => t.token),
+ separatorAt,
+ };
+}
+
+/**
+ * Classify `tokens` exactly as `parseArgs` would walk them, without side effects.
+ *
+ * A `--` makes every following token positional (`parseArgs` forwards them and marks a
+ * positional prompt when any follow). A bare `--resume` (no value) is claudish's
+ * session picker; `--resume <id>` is forwarded with its id.
+ */
+export function classifyPassthroughTokens(tokens: readonly string[]): PassthroughClassification {
+ const out: ClassifiedToken[] = [];
+ const push = (index: number, kind: PassthroughTokenKind) =>
+ out.push({ index, token: tokens[index] as string, kind });
+ let separatorAt: number | null = null;
+ let i = 0;
+ while (i < tokens.length) {
+ const after = classifyStep(tokens, i, push);
+ if (after === -1) {
+ separatorAt = i;
+ break;
+ }
+ i = after;
+ }
+ if (separatorAt !== null) {
+ push(separatorAt, "separator");
+ for (let j = separatorAt + 1; j < tokens.length; j++) push(j, "positional");
+ }
+ return summarizeClassification(out, separatorAt);
+}
+
/**
* Parse CLI arguments and environment variables
*/
@@ -748,7 +1016,7 @@ export async function parseArgs(args: string[]): Promise<ClaudishConfig> {
if (arg === "-p" || arg === "--print") {
config._hasPrintFlag = true;
}
- if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+ if (passthroughFlagTakesValue(args[i + 1])) {
config.claudeArgs.push(args[++i]);
}
} else {