Skip to content

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

feat(mcp): accept one reasoning effort per model from the calling agent

Jack Rudenko09f9cde34cd2
diff --git a/packages/cli/src/mcp-blackbox/provider-fallback.blackbox.test.ts b/packages/cli/src/mcp-blackbox/provider-fallback.blackbox.test.ts
new file mode 100644
index 00000000..090e0ecd
--- /dev/null
+++ b/packages/cli/src/mcp-blackbox/provider-fallback.blackbox.test.ts
@@ -0,0 +1,660 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+ copyFileSync,
+ existsSync,
+ mkdirSync,
+ readFileSync,
+ readdirSync,
+ writeFileSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+ RECOMMENDED_MODELS_CACHE_PATH,
+ type RecommendationCatalogSnapshot,
+ type RecommendationsWire,
+ projectRecommendations,
+} from "../model-loader.js";
+import { ALL_MODELS_CACHE_PATH, writeAllModelsCache } from "../providers/all-models-cache.js";
+import { writeEffortRecommendations } from "../providers/effort-recommendations.js";
+import {
+ MAGMUX_AVAILABLE,
+ PANE_FAKE_CHILD,
+ paneOrphans,
+ paneRootOf,
+ serverEnv,
+} from "../test-helpers/contract-mcp.js";
+import { type TempLayout, makeTempLayout, waitFor } from "../test-helpers/contract-records.js";
+
+const sourceDir = join(import.meta.dir, "..");
+const dataDir = join(sourceDir, "test-fixtures");
+const readJson = <T>(path: string): T => JSON.parse(readFileSync(path, "utf8")) as T;
+const liveDir = join(sourceDir, "fixtures/recommendation-tiers/live");
+const slim = readJson<{ generationId: string; models: RecommendationCatalogSnapshot["entries"] }>(
+ join(liveDir, "slim.json")
+);
+const plans = readJson<{ plans: RecommendationCatalogSnapshot["plans"] }>(
+ join(liveDir, "plans.json")
+);
+const recommended = readJson<{ data: { recommendations: RecommendationsWire } }>(
+ join(liveDir, "recommended.json")
+);
+type Efforts = Record<string, Record<string, { effort: string }>>;
+const efforts = readJson<{ generationId: string; data: { recommendations: { efforts: Efforts } } }>(
+ join(dataDir, "effort-recommendations/recommended-2.3.0.json")
+);
+const rows = readJson<{ entries: Array<{ modelId: string }> }>(
+ join(dataDir, "catalog-v3/rows-g-20260919013346169.json")
+);
+const model = rows.entries[0].modelId;
+const otherModel = rows.entries.at(-1)!.modelId;
+const explicit = `kc@${model}`;
+const effortRows = efforts.data.recommendations.efforts;
+const noRow = rows.entries.find((entry) => !effortRows[entry.modelId])!.modelId;
+const native = Object.keys(effortRows).find((id) => id.startsWith("claude-"))!;
+const printFake = join(sourceDir, "test-helpers/fake-print-claudish.ts");
+const responsePath = join(dataDir, "sse-responses/minimax-m25-turn1-thinking-text-tool.sse");
+
+type Rpc = { jsonrpc: string; id?: number; method?: string; result?: unknown; error?: unknown };
+type ToolAnswer = { content: Array<{ type: string; text: string }>; isError?: boolean };
+
+// The shared client ignores non-JSON stdout lines. This client retains every byte
+// and parses every nonempty line, so logging cannot silently corrupt the protocol.
+class StrictMcp {
+ readonly child;
+ private readonly reader;
+ private readonly stderr;
+ private buffer = "";
+ private nextId = 1;
+ stdout = "";
+
+ constructor(env: Record<string, string>, cwd: string, source: string) {
+ this.child = Bun.spawn([process.execPath, "--no-env-file", "-e", source], {
+ env,
+ cwd,
+ stdin: "pipe",
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ this.reader = this.child.stdout.getReader();
+ this.stderr = new Response(this.child.stderr).text();
+ }
+
+ private write(message: unknown): void {
+ this.child.stdin.write(JSON.stringify(message) + "\n");
+ this.child.stdin.flush();
+ }
+
+ async request(method: string, params: unknown): Promise<unknown> {
+ const id = this.nextId++;
+ this.write({ jsonrpc: "2.0", id, method, params });
+ const timer = setTimeout(() => this.child.kill("SIGKILL"), 60_000);
+ try {
+ for (;;) {
+ const at = this.buffer.indexOf("\n");
+ if (at < 0) {
+ const chunk = await this.reader.read();
+ if (chunk.done) throw new Error("MCP exited: " + (await this.stderr));
+ const text = new TextDecoder().decode(chunk.value);
+ this.stdout += text;
+ this.buffer += text;
+ continue;
+ }
+ const line = this.buffer.slice(0, at);
+ this.buffer = this.buffer.slice(at + 1);
+ if (!line.trim()) continue;
+ const message = JSON.parse(line) as Rpc;
+ expect(message.jsonrpc).toBe("2.0");
+ if (message.method && message.id !== undefined) {
+ this.write({ jsonrpc: "2.0", id: message.id, result: {} });
+ } else if (message.id === id) {
+ expect(message.error).toBeUndefined();
+ return message.result;
+ }
+ }
+ } finally {
+ clearTimeout(timer);
+ }
+ }
+
+ async initialize(): Promise<void> {
+ await this.request("initialize", {
+ protocolVersion: "2025-06-18",
+ capabilities: {},
+ clientInfo: { name: "provider-fallback-test", version: "1.0.0" },
+ });
+ this.write({ jsonrpc: "2.0", method: "notifications/initialized" });
+ }
+
+ async tool(name: string, args: Record<string, unknown> = {}): Promise<ToolAnswer> {
+ return (await this.request("tools/call", { name, arguments: args })) as ToolAnswer;
+ }
+
+ async close(): Promise<void> {
+ this.child.stdin.end();
+ const timer = setTimeout(() => this.child.kill("SIGKILL"), 15_000);
+ try {
+ for (;;) {
+ const chunk = await this.reader.read();
+ if (chunk.done) break;
+ this.stdout += new TextDecoder().decode(chunk.value);
+ }
+ await this.child.exited;
+ expect(this.child.exitCode).toBe(0);
+ for (const line of this.stdout.split("\n").filter((line) => line.trim())) {
+ expect((JSON.parse(line) as Rpc).jsonrpc).toBe("2.0");
+ }
+ } finally {
+ clearTimeout(timer);
+ this.reader.releaseLock();
+ await this.stderr;
+ }
+ }
+}
+
+let layout: TempLayout;
+let server: StrictMcp | undefined;
+let config: string;
+let fetches: string;
+let requests: string;
+let argvDir: string;
+
+beforeEach(() => {
+ layout = makeTempLayout("provider-fallback");
+ config = join(layout.home, ".claudish");
+ fetches = join(layout.root, "blocked-fetches.jsonl");
+ requests = join(layout.root, "proxy-requests.jsonl");
+ argvDir = join(layout.root, "argv");
+ mkdirSync(config, { recursive: true });
+ mkdirSync(argvDir);
+ copyFileSync(
+ join(dataDir, "catalog-v3/wire-g-20261012101007285-7770c36e.json"),
+ join(config, basename(ALL_MODELS_CACHE_PATH))
+ );
+ writeEffortRecommendations(
+ efforts.generationId,
+ efforts.data.recommendations.efforts,
+ join(config, "cloud-models-catalog-v3.efforts.json")
+ );
+ server = undefined;
+});
+
+afterEach(async () => {
+ try {
+ await server?.close();
+ expect(await paneOrphans(layout)).toEqual({ processes: [], files: [] });
+ } finally {
+ layout.cleanup();
+ }
+}, 30_000);
+
+async function start(): Promise<StrictMcp> {
+ const wrapper = join(layout.root, "pane-child.ts");
+ writeFileSync(
+ wrapper,
+ `
+ import { writeFileSync } from "node:fs";
+ import { join } from "node:path";
+ const args = process.argv.slice(2);
+ if (args.includes("-p")) {
+ writeFileSync(${JSON.stringify(join(layout.root, "native-argv.json"))}, JSON.stringify(args));
+ process.argv[process.argv.indexOf("--model") + 1] = "claude-fake-ok";
+ await import(${JSON.stringify(pathToFileURL(printFake).href)});
+ process.exit(0);
+ }
+ const id = args[args.indexOf("--session-id") + 1];
+ writeFileSync(join(${JSON.stringify(argvDir)}, id + ".json"), JSON.stringify(args));
+ await import(${JSON.stringify(pathToFileURL(PANE_FAKE_CHILD).href)});
+ `
+ );
+ const source = `
+ import { appendFileSync, readFileSync } from "node:fs";
+ import { homedir } from "node:os";
+ if (homedir() !== process.env.HOME) throw new Error("HOME is not isolated");
+ const originalFetch = globalThis.fetch;
+ const blocked = (url) => {
+ appendFileSync(${JSON.stringify(fetches)}, JSON.stringify(String(url)) + "\\n");
+ throw new Error("Network blocked by test: " + url);
+ };
+ const intercepted = async (input, init) => {
+ const url = new URL(typeof input === "string" ? input : input.url ?? input.href);
+ if (url.protocol === "data:") return originalFetch(input, init);
+ if (url.protocol === "http:" && url.hostname === "127.0.0.1" &&
+ url.pathname === "/v1/messages" && init?.method === "POST") {
+ appendFileSync(${JSON.stringify(requests)}, init.body + "\\n");
+ return new Response(readFileSync(${JSON.stringify(responsePath)}, "utf8"),
+ { headers: { "Content-Type": "text/event-stream" } });
+ }
+ return blocked(url.href);
+ };
+ intercepted.preconnect = blocked;
+ globalThis.fetch = intercepted;
+ const { startMcpServer } = await import(${JSON.stringify(pathToFileURL(join(sourceDir, "mcp-server.ts")).href)});
+ startMcpServer();
+ `;
+ server = new StrictMcp(
+ serverEnv(layout, {
+ CLAUDISH_BIN: wrapper,
+ FAKE_PRINT_RECORD: join(layout.root, "native-print-record.json"),
+ }),
+ layout.cwd,
+ source
+ );
+ await server.initialize();
+ return server;
+}
+
+const textOf = (answer: ToolAnswer): string => answer.content.map((part) => part.text).join("\n");
+const capturedArgv = (): string[][] =>
+ readdirSync(argvDir).map((file) => readJson<string[]>(join(argvDir, file)));
+const modelOf = (argv: string[]): string => argv[argv.indexOf("--model") + 1];
+
+function seedListing(stale: boolean): ReturnType<typeof projectRecommendations> {
+ const doc = projectRecommendations(
+ recommended.data.recommendations,
+ { catalogGenerationId: slim.generationId, entries: slim.models, plans: plans.plans },
+ [],
+ stale ? new Date(0) : new Date()
+ );
+ writeFileSync(join(config, basename(RECOMMENDED_MODELS_CACHE_PATH)), JSON.stringify(doc));
+ return doc;
+}
+
+function logs(): string {
+ return readdirSync(join(config, "logs"))
+ .filter((name) => name.startsWith("claudish-mcp_"))
+ .map((name) => readFileSync(join(config, "logs", name), "utf8"))
+ .join("\n");
+}
+
+describe("list_models fallback over isolated JSON-RPC", () => {
+ test("failed fetch uses an expired different-generation listing, adds efforts and logs only to file", async () => {
+ const doc = seedListing(true);
+ const mcp = await start();
+ const answer = await mcp.tool("list_models");
+ expect(answer.isError).not.toBe(true);
+ const text = textOf(answer);
+ expect(text).toStartWith(
+ "_The live catalog could not be read; this list is from generation " + doc.generationId
+ );
+ expect(text).toContain(doc.models[0].id);
+ expect(text).not.toContain("**Access**");
+ expect(text).not.toContain("@");
+ expect(text).toContain("Pass each model by its bare id");
+ expect(text).toContain("Recommended effort by task type");
+ expect(text).toContain("implementation");
+ expect(text).toContain("claude-opus-5-5");
+ expect(readFileSync(fetches, "utf8")).toContain("catalog=recommended");
+ await waitFor(() => logs().includes("[mcp] list_models:"), { what: "fallback log flush" });
+ expect(logs()).toContain("[mcp] list_models: Unable to load v3 recommended models:");
+ expect(logs()).toContain("answered from stored generation " + doc.generationId);
+ expect(mcp.stdout).not.toContain("\n[mcp]");
+ }, 15_000);
+
+ test("efforts are appended even when there is no listing", async () => {
+ const mcp = await start();
+ const text = textOf(await mcp.tool("list_models"));
+ expect(text).toStartWith("No recommended models found. Try search_models instead.");
+ expect(text).toContain("Recommended effort by task type");
+ expect(text).toContain("implementation");
+ }, 15_000);
+
+ test("a current cached listing also includes the efforts table without a fallback note", async () => {
+ const doc = seedListing(false);
+ writeAllModelsCache(
+ {
+ version: 3,
+ catalogGenerationId: slim.generationId,
+ lastUpdated: new Date().toISOString(),
+ entries: slim.models,
+ plans: plans.plans,
+ models: slim.models.map((entry) => ({ id: entry.modelId })),
+ },
+ join(config, basename(ALL_MODELS_CACHE_PATH))
+ );
+ const mcp = await start();
+ const text = textOf(await mcp.tool("list_models"));
+ expect(text).toContain(doc.models[0].id);
+ expect(text).not.toContain("**Access**");
+ expect(text).not.toContain("@");
+ expect(text).toContain("Pass each model by its bare id");
+ expect(text).not.toContain("_The live catalog could not be read;");
+ expect(text).toContain("Recommended effort by task type");
+ }, 15_000);
+});
+
+function assertNothingStarted(teamPath?: string): void {
+ if (teamPath) expect(existsSync(teamPath)).toBe(false);
+ expect(readdirSync(layout.sessionsDir)).toEqual([]);
+ expect(capturedArgv()).toEqual([]);
+ expect(existsSync(requests)).toBe(false);
+ expect(existsSync(join(layout.root, "native-argv.json"))).toBe(false);
+ const paneRoot = paneRootOf(layout);
+ expect(existsSync(paneRoot) ? readdirSync(paneRoot, { recursive: true }) : []).toEqual([]);
+}
+
+function expectedEfforts(spec: string, id = model): Record<string, Record<string, string>> {
+ return {
+ [spec]: Object.fromEntries(
+ Object.entries(effortRows[id]).map(([task, cell]) => [task, cell.effort])
+ ),
+ };
+}
+
+function expectNeedsEffort(
+ answer: ToolAnswer,
+ expected: Record<string, Record<string, string>>
+): void {
+ expect(answer.isError).toBe(true);
+ expect(textOf(answer)).toStartWith("needs_effort:");
+ expect(JSON.parse(textOf(answer).split("Recommended levels: ")[1])).toEqual(expected);
+}
+
+describe("needs_effort over isolated JSON-RPC", () => {
+ test.each([model, explicit])(
+ "run_prompt needs_effort starts nothing for %s",
+ async (spec) => {
+ const mcp = await start();
+ const answer = await mcp.tool("run_prompt", { model: spec, prompt: "Answer this input." });
+ assertNothingStarted();
+ expectNeedsEffort(answer, expectedEfforts(spec));
+ },
+ 15_000
+ );
+
+ test.skipIf(!MAGMUX_AVAILABLE).each([model, explicit])(
+ "create_session needs_effort starts nothing for %s",
+ async (spec) => {
+ const mcp = await start();
+ const answer = await mcp.tool("create_session", {
+ model: spec,
+ prompt: "Answer this input.",
+ });
+ assertNothingStarted();
+ expectNeedsEffort(answer, expectedEfforts(spec));
+ },
+ 15_000
+ );
+
+ test.each(["run", "run-and-judge"])(
+ "team %s needs_effort starts nothing with caller-spelled keys",
+ async (mode) => {
+ const mcp = await start();
+ const path = join(layout.cwd, "must-not-exist");
+ const answer = await mcp.tool("team", {
+ mode,
+ path,
+ models: [explicit, model, noRow, native],
+ judges: [explicit, model],
+ input: "Answer this input.",
+ });
+ assertNothingStarted(path);
+ expectNeedsEffort(answer, { ...expectedEfforts(explicit), ...expectedEfforts(model) });
+ },
+ 15_000
+ );
+
+ test("run_prompt default runs without output_config", async () => {
+ const mcp = await start();
+ const answer = await mcp.tool("run_prompt", {
+ model: explicit,
+ prompt: "Answer this input.",
+ effort: "default",
+ });
+ expect(answer.isError).not.toBe(true);
+ const bodies = readFileSync(requests, "utf8")
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line));
+ expect(bodies).toHaveLength(1);
+ expect(bodies[0].model).toBe(model);
+ expect(Object.hasOwn(bodies[0], "output_config")).toBe(false);
+ expect(capturedArgv()).toEqual([]);
+ }, 15_000);
+
+ test("a model with no row runs run_prompt without clarification or output_config", async () => {
+ expect(effortRows[noRow]).toBeUndefined();
+ const mcp = await start();
+ const answer = await mcp.tool("run_prompt", { model: noRow, prompt: "Answer this input." });
+ expect(answer.isError).not.toBe(true);
+ const body = JSON.parse(readFileSync(requests, "utf8").trim());
+ expect(body.model).toBe(noRow);
+ expect(Object.hasOwn(body, "output_config")).toBe(false);
+ }, 15_000);
+
+ test("a native name with a row runs the fake print child without clarification", async () => {
+ expect(effortRows[native]).toBeDefined();
+ const mcp = await start();
+ const answer = await mcp.tool("run_prompt", { model: native, prompt: "Answer this input." });
+ expect(answer.isError).not.toBe(true);
+ expect(textOf(answer)).toContain("7723");
+ const argv = readJson<string[]>(join(layout.root, "native-argv.json"));
+ expect(modelOf(argv)).toBe(native);
+ expect(argv).not.toContain("--effort-override");
+ expect(existsSync(requests)).toBe(false);
+ }, 15_000);
+
+ test("a newer empty sidecar generation does not reuse an older model row", async () => {
+ const path = join(config, "cloud-models-catalog-v3.efforts.json");
+ const sidecar = readJson<{
+ contractVersion: number;
+ format: number;
+ generations: Record<string, { writtenAt: number; efforts: unknown }>;
+ }>(path);
+ expect(slim.generationId).not.toBe(efforts.generationId);
+ sidecar.generations[efforts.generationId].writtenAt = 1;
+ sidecar.generations[slim.generationId] = { writtenAt: 2, efforts: {} };
+ writeFileSync(path, JSON.stringify(sidecar));
+ const mcp = await start();
+ const answer = await mcp.tool("run_prompt", { model, prompt: "Answer this input." });
+ expect(answer.isError).not.toBe(true);
+ const body = JSON.parse(readFileSync(requests, "utf8").trim());
+ expect(body.model).toBe(model);
+ expect(Object.hasOwn(body, "output_config")).toBe(false);
+ }, 15_000);
+
+ test("MCP startup retains 500 logs for its own name", async () => {
+ const dir = join(config, "logs");
+ mkdirSync(dir);
+ const originals = Array.from(
+ { length: 502 },
+ (_, i) => `claudish-mcp_2000-${String(i).padStart(4, "0")}_1.log`
+ );
+ for (const name of originals) writeFileSync(join(dir, name), "old mcp log");
+ const other = "claudish_2000-01-01_1.log";
+ writeFileSync(join(dir, other), "session log");
+ await start();
+ const names = readdirSync(dir).sort();
+ const mcp = names.filter((name) => name.startsWith("claudish-mcp_"));
+ expect(mcp).toHaveLength(500);
+ expect(mcp.slice(0, -1)).toEqual(originals.slice(3));
+ expect(readFileSync(join(dir, other), "utf8")).toBe("session log");
+ }, 15_000);
+});
+
+describe.skipIf(!MAGMUX_AVAILABLE)("effort opt-outs and exempt pane models", () => {
+ test("create_session default starts without an effort override", async () => {
+ const mcp = await start();
+ const answer = await mcp.tool("create_session", {
+ model: explicit,
+ prompt: "Answer this input.",
+ effort: "default",
+ });
+ expect(answer.isError).not.toBe(true);
+ const args = await waitFor(() => capturedArgv()[0], { what: "default session argv" });
+ expect(modelOf(args)).toBe(model);
+ expect(args).not.toContain("--effort-override");
+ }, 30_000);
+
+ test.each(["run", "run-and-judge"])(
+ "team %s with efforts {} starts every slot without an override",
+ async (mode) => {
+ const mcp = await start();
+ const answer = await mcp.tool("team", {
+ mode,
+ path: join(layout.cwd, "keep-effort"),
+ models: [explicit, model],
+ judges: [explicit, model],
+ input: "Answer this input.",
+ efforts: {},
+ });
+ expect(answer.isError).not.toBe(true);
+ const count = mode === "run" ? 2 : 4;
+ const args = await waitFor(() => capturedArgv().length === count && capturedArgv(), {
+ what: "all default-effort team children",
+ });
+ expect(args).toHaveLength(count);
+ for (const argv of args) expect(argv).not.toContain("--effort-override");
+ },
+ 90_000
+ );
+
+ test.each([noRow, native])(
+ "create_session exempts %s without effort",
+ async (spec) => {
+ const mcp = await start();
+ const answer = await mcp.tool("create_session", {
+ model: spec,
+ prompt: "Answer this input.",
+ });
+ expect(answer.isError).not.toBe(true);
+ const args = await waitFor(() => capturedArgv()[0], { what: "exempt session argv" });
+ expect(modelOf(args)).toBe(spec);
+ expect(args).not.toContain("--effort-override");
+ },
+ 30_000
+ );
+
+ test("team without any matching foreign row starts as before", async () => {
+ const mcp = await start();
+ const answer = await mcp.tool("team", {
+ mode: "run",
+ path: join(layout.cwd, "exempt-models"),
+ models: [noRow, native],
+ input: "Answer this input.",
+ });
+ expect(answer.isError).not.toBe(true);
+ const args = await waitFor(() => capturedArgv().length === 2 && capturedArgv(), {
+ what: "exempt team children",
+ });
+ expect(args.map(modelOf).sort()).toEqual([noRow, native].sort());
+ for (const argv of args) expect(argv).not.toContain("--effort-override");
+ }, 45_000);
+});
+
+describe("run_prompt provider intent over isolated JSON-RPC", () => {
+ test("strips an unrequested provider but preserves a required provider in the actual proxy body", async () => {
+ const mcp = await start();
+ for (const required of [undefined, false, true]) {
+ const answer = await mcp.tool("run_prompt", {
+ model: explicit,
+ prompt: "Return the captured answer.",
+ effort: "default",
+ ...(required === undefined ? {} : { user_required_provider: required }),
+ });
+ expect(answer.isError).not.toBe(true);
+ expect(textOf(answer).includes("Provider removed so claudish routing decides:")).toBe(
+ required !== true
+ );
+ }
+ const bodies = readFileSync(requests, "utf8")
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line) as { model: string });
+ expect(bodies.map((body) => body.model)).toEqual([model, model, explicit]);
+ }, 20_000);
+
+ test("compare_models is not subject to provider stripping", async () => {
+ const mcp = await start();
+ const answer = await mcp.tool("compare_models", {
+ models: [explicit, `openrouter@${otherModel}`],
+ prompt: "Return the captured answer.",
+ });
+ expect(answer.isError).not.toBe(true);
+ const bodies = readFileSync(requests, "utf8")
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line) as { model: string });
+ expect(bodies.map((body) => body.model).sort()).toEqual(
+ [explicit, `openrouter@${otherModel}`].sort()
+ );
+ }, 20_000);
+});
+
+describe.skipIf(!MAGMUX_AVAILABLE)(
+ "provider intent in real panes with captured fake-child behaviour",
+ () => {
+ test("create_session strips by default and keeps an explicitly required provider", async () => {
+ const mcp = await start();
+ for (const required of [false, true]) {
+ const answer = await mcp.tool("create_session", {
+ model: explicit,
+ prompt: "Answer this input.",
+ effort: "default",
+ user_required_provider: required,
+ });
+ expect(answer.isError).not.toBe(true);
+ const body = JSON.parse(textOf(answer)) as {
+ session_id: string;
+ model?: string;
+ note?: string;
+ };
+ const record = readJson<{ model: string }>(
+ join(layout.sessionsDir, body.session_id, "spawn.json")
+ );
+ expect(record.model).toBe(required ? explicit : model);
+ expect(body.note?.includes("Provider removed")).toBe(required ? undefined : true);
+ const expectedModel = required ? explicit : model;
+ const argv = await waitFor(
+ () => capturedArgv().find((args) => modelOf(args) === expectedModel),
+ { what: "session child argv" }
+ );
+ expect(modelOf(argv)).toBe(expectedModel);
+ }
+ }, 30_000);
+
+ test("team keeps caller-spelled efforts mapped to stripped slots and preserves required providers", async () => {
+ const mcp = await start();
+ const judge = `openrouter@${otherModel}`;
+ const path = join(layout.cwd, "team");
+ const answer = await mcp.tool("team", {
+ mode: "run",
+ path,
+ models: [explicit, judge],
+ input: "Answer this input.",
+ user_required_provider: [judge],
+ efforts: { [explicit]: "low", [judge]: "high" },
+ });
+ expect(answer.isError).not.toBe(true);
+ expect(textOf(answer)).toContain(`${explicit} -> ${model}`);
+ expect(textOf(answer)).not.toContain(`${judge} ->`);
+ const args = await waitFor(() => capturedArgv().length >= 2 && capturedArgv(), {
+ what: "two team children",
+ });
+ const byModel = new Map(args.map((argv) => [modelOf(argv), argv]));
+ expect([...byModel.keys()].sort()).toEqual([model, judge].sort());
+ expect(byModel.get(model)?.slice(-2)).toEqual(["--effort-override", "low"]);
+ expect(byModel.get(judge)?.slice(-2)).toEqual(["--effort-override", "high"]);
+ }, 45_000);
+
+ test("team judges use the same provider-intent set as models", async () => {
+ const mcp = await start();
+ const firstJudge = `openrouter@${model}`;
+ const secondJudge = `openrouter@${otherModel}`;
+ const answer = await mcp.tool("team", {
+ mode: "run-and-judge",
+ path: join(layout.cwd, "judged"),
+ models: [explicit, `kc@${otherModel}`],
+ judges: [firstJudge, secondJudge],
+ efforts: {},
+ user_required_provider: [secondJudge],
+ input: "Answer this input.",
+ });
+ expect(answer.isError).not.toBe(true);
+ const args = capturedArgv();
+ expect(args.map(modelOf).sort()).toEqual([model, otherModel, model, secondJudge].sort());
+ expect(textOf(answer)).toContain(`${firstJudge} -> ${model}`);
+ expect(textOf(answer)).not.toContain(`${secondJudge} ->`);
+ }, 90_000);
+ }
+);
diff --git a/packages/cli/src/mcp-blackbox/tool-surface.blackbox.test.ts b/packages/cli/src/mcp-blackbox/tool-surface.blackbox.test.ts
index 3fdba8f1..77eeaf55 100644
--- a/packages/cli/src/mcp-blackbox/tool-surface.blackbox.test.ts
+++ b/packages/cli/src/mcp-blackbox/tool-surface.blackbox.test.ts
@@ -204,9 +204,11 @@ describe("quick-prompt public surface", () => {
expect(prompt).toBeDefined();
expect(compare).toBeDefined();
expect(Object.keys(prompt?.inputSchema?.properties ?? {}).sort()).toEqual([
+ "effort",
"model",
"prompt",
"system_prompt",
+ "user_required_provider",
]);
expect(prompt?.inputSchema?.required).toEqual(["model", "prompt"]);
expect(prompt?.inputSchema?.properties).not.toHaveProperty("max_tokens");
@@ -299,6 +301,7 @@ describe("tool list (FR11, §4)", () => {
"path",
"require_pattern",
"min_output_bytes",
+ "user_required_provider",
])
expect(Object.keys(props)).toContain(p);
@@ -306,6 +309,9 @@ describe("tool list (FR11, §4)", () => {
const capProps = Object.keys(cap?.inputSchema?.properties ?? {}).sort();
expect(capProps).toEqual(["session_id", "since_seq", "spans"]);
expect(cap?.inputSchema?.required).toEqual(["session_id"]);
+ expect(
+ tools.find((tool) => tool.name === "create_session")?.inputSchema?.properties
+ ).toHaveProperty("user_required_provider");
});
});
diff --git a/packages/cli/src/mcp-effort-args.test.ts b/packages/cli/src/mcp-effort-args.test.ts
new file mode 100644
index 00000000..252419f9
--- /dev/null
+++ b/packages/cli/src/mcp-effort-args.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { effortArg, modelEffortsArg } from "./mcp-server.js";
+
+const LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const capture = JSON.parse(
+ readFileSync(
+ join(import.meta.dir, "test-fixtures/effort-recommendations/recommended-2.3.0.json"),
+ "utf8"
+ )
+) as { data: { recommendations: { efforts: Record<string, unknown> } } };
+const capturedModels = Object.keys(capture.data.recommendations.efforts);
+const models = capturedModels.slice(0, 2);
+
+describe("effortArg", () => {
+ test.each([undefined, null, "", "default"].map((value) => ({ value })))(
+ "treats $value as absent",
+ ({ value }) => {
+ expect(effortArg(value)).toBeUndefined();
+ }
+ );
+
+ test.each([...LEVELS])("returns the canonical level %s unchanged", (level) => {
+ expect(effortArg(level)).toBe(level);
+ });
+
+ test.each(["High", "ultra", 3].map((value) => ({ value })))(
+ "rejects $value and names every valid level",
+ ({ value }) => {
+ expect(() => effortArg(value)).toThrow(LEVELS.join(", "));
+ expect(() => effortArg(value)).toThrow("Invalid 'effort'");
+ expect(() => effortArg(value)).toThrow('"default"');
+ }
+ );
+});
+
+describe("modelEffortsArg", () => {
+ test.each([undefined, null, {}].map((value) => ({ value })))(
+ "treats absent or empty efforts $value as undefined",
+ ({ value }) => {
+ expect(modelEffortsArg(value, models)).toBeUndefined();
+ }
+ );
+
+ test("returns a valid per-model map without mutating the caller's input", () => {
+ const value = Object.freeze({ [models[0]]: "high", [models[1]]: "minimal" });
+ const beforeModels = [...models];
+ expect(modelEffortsArg(value, models)).toEqual(value);
+ expect(value).toEqual({ [models[0]]: "high", [models[1]]: "minimal" });
+ expect(models).toEqual(beforeModels);
+ });
+
+ test("permits a partial map without filling in the other model", () => {
+ expect(modelEffortsArg({ [models[1]]: "max" }, models)).toEqual({
+ [models[1]]: "max",
+ });
+ });
+
+ test.each([...LEVELS])("accepts the canonical level %s in a map", (level) => {
+ expect(modelEffortsArg({ [models[0]]: level }, models)).toEqual({
+ [models[0]]: level,
+ });
+ });
+
+ test.each([capturedModels[2], `or@${models[0]}`])(
+ "rejects a key %s that is not an exact models entry and names the allowed keys",
+ (key) => {
+ const call = () => modelEffortsArg({ [key]: "high" }, models);
+ expect(call).toThrow(key);
+ expect(call).toThrow(models.join(", "));
+ expect(call).toThrow("Keys must match a 'models' entry exactly");
+ }
+ );
+
+ test.each(["High", "ultra", 3, undefined, null, ""].map((level) => ({ level })))(
+ "rejects invalid map level $level, naming the model and every valid level",
+ ({ level }) => {
+ const call = () => modelEffortsArg({ [models[0]]: level }, models);
+ expect(call).toThrow(models[0]);
+ expect(call).toThrow(LEVELS.join(", "));
+ }
+ );
+
+ test.each([[], ["high"], "high"].map((value) => ({ value })))(
+ "rejects non-object efforts $value",
+ ({ value }) => {
+ expect(() => modelEffortsArg(value, models)).toThrow("expected an object");
+ }
+ );
+});
diff --git a/packages/cli/src/mcp-effort-clarification.test.ts b/packages/cli/src/mcp-effort-clarification.test.ts
new file mode 100644
index 00000000..f8a2dc66
--- /dev/null
+++ b/packages/cli/src/mcp-effort-clarification.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { KEEP_EFFORT, effortArg, effortClarification } from "./mcp-server.js";
+
+type Efforts = Record<string, Record<string, { effort: string }>>;
+const captured = JSON.parse(
+ readFileSync(
+ join(import.meta.dir, "test-fixtures/effort-recommendations/recommended-2.3.0.json"),
+ "utf8"
+ )
+) as { data: { recommendations: { efforts: Efforts } } };
+const efforts = captured.data.recommendations.efforts;
+const foreign = "gpt-6-luna";
+const native = Object.keys(efforts).find((id) => id.startsWith("claude-"))!;
+const rows = JSON.parse(
+ readFileSync(
+ join(import.meta.dir, "test-fixtures/catalog-v3/rows-g-20260919013346169.json"),
+ "utf8"
+ )
+) as { entries: Array<{ modelId: string }> };
+const missing = rows.entries.find((entry) => !efforts[entry.modelId])!.modelId;
+const levels = (id: string) =>
+ Object.fromEntries(Object.entries(efforts[id]).map(([task, cell]) => [task, cell.effort]));
+
+describe("effortClarification with real efforts data", () => {
+ test("the data has native and foreign rows and a captured model with no row", () => {
+ expect(efforts[foreign]).toBeDefined();
+ expect(efforts[native]).toBeDefined();
+ expect(efforts[missing]).toBeUndefined();
+ expect(KEEP_EFFORT).toBe("default");
+ expect(effortArg(KEEP_EFFORT)).toBeUndefined();
+ });
+
+ const cases: Array<{
+ name: string;
+ specs: string[];
+ expected: Record<string, Record<string, string>> | undefined;
+ }> = [
+ { name: "bare canonical id", specs: [foreign], expected: { [foreign]: levels(foreign) } },
+ {
+ name: "provider lookup preserves caller key",
+ specs: [`oai@${foreign}`],
+ expected: { [`oai@${foreign}`]: levels(foreign) },
+ },
+ {
+ name: "multiple spellings stay separate",
+ specs: [foreign, `cx@${foreign}`],
+ expected: { [foreign]: levels(foreign), [`cx@${foreign}`]: levels(foreign) },
+ },
+ { name: "native row skipped", specs: [native], expected: undefined },
+ {
+ name: "native aliases skipped",
+ specs: ["opus", "sonnet", "haiku", "internal"],
+ expected: undefined,
+ },
+ {
+ name: "explicit Claude is foreign",
+ specs: [`anthropic@${native}`],
+ expected: { [`anthropic@${native}`]: levels(native) },
+ },
+ { name: "no matching row", specs: [missing], expected: undefined },
+ {
+ name: "mixed models only return matching foreign rows",
+ specs: [native, missing, `oai@${foreign}`],
+ expected: { [`oai@${foreign}`]: levels(foreign) },
+ },
+ { name: "empty specs", specs: [], expected: undefined },
+ ];
+ test.each(cases)("$name", ({ specs, expected }) => {
+ const before = structuredClone(efforts);
+ const frozen = Object.freeze([...specs]);
+ expect(effortClarification(frozen, efforts)).toEqual(expected);
+ expect(efforts).toEqual(before);
+ expect(frozen).toEqual(specs);
+ });
+
+ test("an injected empty map never consults the disk sidecar", () => {
+ expect(effortClarification([foreign], {})).toBeUndefined();
+ });
+
+ test("returned rows do not alias the injected cells", () => {
+ const copy = structuredClone(efforts);
+ const result = effortClarification([foreign], copy)!;
+ const task = Object.keys(result[foreign])[0];
+ result[foreign][task] = "changed by caller";
+ expect(copy[foreign][task].effort).toBe(efforts[foreign][task].effort);
+ });
+});
diff --git a/packages/cli/src/mcp-provider-strip.test.ts b/packages/cli/src/mcp-provider-strip.test.ts
new file mode 100644
index 00000000..f1cee6e9
--- /dev/null
+++ b/packages/cli/src/mcp-provider-strip.test.ts
@@ -0,0 +1,159 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import {
+ stripUnrequestedProvider,
+ strippedProviders,
+ userRequiredProvidersArg,
+} from "./mcp-server.js";
+
+const capture = JSON.parse(
+ readFileSync(
+ new URL("./test-fixtures/catalog-v3/rows-g-20260919013346169.json", import.meta.url),
+ "utf8"
+ )
+) as { entries: Array<{ modelId: string; aliases?: string[] }> };
+const canonicalIds = new Set(capture.entries.map((entry) => entry.modelId));
+const model = capture.entries[0].modelId;
+const secondModel = capture.entries.at(-1)!.modelId;
+const wireId = capture.entries[0].aliases!.find((id) => id === "k3")!;
+const isCatalogModel = (id: string): boolean => canonicalIds.has(id);
+
+describe("stripUnrequestedProvider with captured canonical model ids", () => {
+ test("uses real canonical ids and a distinct captured wire id", () => {
+ expect(model).toBe("kimi-k3");
+ expect(canonicalIds.has(secondModel)).toBe(true);
+ expect(wireId).toBe("k3");
+ expect(canonicalIds.has(wireId)).toBe(false);
+ });
+
+ test.each([
+ { name: "catalog model", spec: `kc@${model}`, required: false, expected: model },
+ {
+ name: "explicitly required provider",
+ spec: `kc@${model}`,
+ required: true,
+ expected: `kc@${model}`,
+ },
+ {
+ name: "non-canonical wire id",
+ spec: `kc@${wireId}`,
+ required: false,
+ expected: `kc@${wireId}`,
+ },
+ { name: "Ollama", spec: `ollama@${model}`, required: false, expected: `ollama@${model}` },
+ {
+ name: "LM Studio",
+ spec: `lmstudio@${model}`,
+ required: false,
+ expected: `lmstudio@${model}`,
+ },
+ {
+ name: "HTTP endpoint",
+ spec: `http://localhost:8000@${model}`,
+ required: false,
+ expected: `http://localhost:8000@${model}`,
+ },
+ {
+ name: "HTTPS endpoint",
+ spec: `https://endpoint.test/v1@${model}`,
+ required: false,
+ expected: `https://endpoint.test/v1@${model}`,
+ },
+ {
+ name: "routing chain",
+ spec: `kc@${model}+openrouter@${secondModel}`,
+ required: false,
+ expected: `kc@${model}+openrouter@${secondModel}`,
+ },
+ { name: "+pro marker", spec: `kc@${model}+pro`, required: false, expected: `${model}+pro` },
+ { name: "#fast marker", spec: `kc@${model}#fast`, required: false, expected: `${model}#fast` },
+ {
+ name: "required markers",
+ spec: `kc@${model}+pro#fast`,
+ required: true,
+ expected: `kc@${model}+pro#fast`,
+ },
+ { name: "bare name", spec: model, required: false, expected: model },
+ {
+ name: "bare name with marker",
+ spec: `${model}+pro`,
+ required: false,
+ expected: `${model}+pro`,
+ },
+ { name: "legacy syntax", spec: `kc/${model}`, required: false, expected: `kc/${model}` },
+ {
+ name: "canonical id with different case",
+ spec: `kc@${model.toUpperCase()}`,
+ required: false,
+ expected: `kc@${model.toUpperCase()}`,
+ },
+ ])("$name", ({ spec, required, expected }) => {
+ expect(stripUnrequestedProvider(spec, required, isCatalogModel)).toBe(expected);
+ });
+});
+
+describe("userRequiredProvidersArg", () => {
+ const specs = [`kc@${model}`, `openrouter@${secondModel}`];
+
+ for (const value of [undefined, null, []]) {
+ test(`${JSON.stringify(value) ?? "undefined"} means no required provider`, () => {
+ expect([...userRequiredProvidersArg(value, specs)]).toEqual([]);
+ });
+ }
+
+ test("accepts exact model and judge specs and deduplicates them", () => {
+ expect([...userRequiredProvidersArg([specs[1], specs[0], specs[1]], specs)]).toEqual([
+ specs[1],
+ specs[0],
+ ]);
+ });
+
+ for (const value of [true, false, 1, "", specs[0], {}, [null], [1], [specs[0], false]]) {
+ test(`rejects non-array/non-string input ${JSON.stringify(value)}`, () => {
+ expect(() => userRequiredProvidersArg(value, specs)).toThrow(
+ "Invalid 'user_required_provider': expected an array of model specs."
+ );
+ });
+ }
+
+ test("rejects an entry absent from models/judges and names the available specs", () => {
+ expect(() => userRequiredProvidersArg([model], specs)).toThrow(
+ `Invalid 'user_required_provider': ${JSON.stringify(model)} is not one of the models (${specs.join(", ")}). Entries must match a 'models' or 'judges' entry exactly.`
+ );
+ });
+});
+
+describe("strippedProviders", () => {
+ test("returns stripped specs and ordered notes without mutating caller spellings", () => {
+ const specs = [
+ `kc@${model}+pro`,
+ `ollama@${model}`,
+ `openrouter@${secondModel}#fast`,
+ `kc@${model}`,
+ model,
+ `kc@${model}+pro`,
+ ];
+ const original = [...specs];
+ expect(strippedProviders(specs, new Set([`kc@${model}`]), isCatalogModel)).toEqual({
+ specs: [`${model}+pro`, specs[1], `${secondModel}#fast`, specs[3], model, `${model}+pro`],
+ stripped: [
+ { from: specs[0], to: `${model}+pro` },
+ { from: specs[2], to: `${secondModel}#fast` },
+ { from: specs[5], to: `${model}+pro` },
+ ],
+ });
+ expect(specs).toEqual(original);
+ });
+
+ test("all required specs stay unchanged with no note", () => {
+ const specs = [`kc@${model}`, `openrouter@${secondModel}`];
+ expect(strippedProviders(specs, new Set(specs), isCatalogModel)).toEqual({
+ specs,
+ stripped: [],
+ });
+ });
+
+ test("empty input returns empty arrays", () => {
+ expect(strippedProviders([], new Set(), isCatalogModel)).toEqual({ specs: [], stripped: [] });
+ });
+});
diff --git a/packages/cli/src/mcp-run-prompt-effort.test.ts b/packages/cli/src/mcp-run-prompt-effort.test.ts
new file mode 100644
index 00000000..b763ab63
--- /dev/null
+++ b/packages/cli/src/mcp-run-prompt-effort.test.ts
@@ -0,0 +1,171 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const capture = JSON.parse(
+ readFileSync(
+ join(import.meta.dir, "test-fixtures/effort-recommendations/recommended-2.3.0.json"),
+ "utf8"
+ )
+) as { data: { recommendations: { efforts: Record<string, unknown> } } };
+const model = Object.keys(capture.data.recommendations.efforts)[1];
+const prompt = "Return the captured answer.";
+const system = "Use only the supplied response.";
+const responsePath = join(
+ import.meta.dir,
+ "test-fixtures/sse-responses/minimax-m25-turn1-thinking-text-tool.sse"
+);
+const expectedText = readFileSync(responsePath, "utf8")
+ .split("\n")
+ .filter((line) => line.startsWith("data: "))
+ .map((line) => JSON.parse(line.slice(6)))
+ .filter((event) => event.type === "content_block_delta" && event.delta?.type === "text_delta")
+ .map((event) => event.delta.text)
+ .join("");
+
+type RequestBody = Record<string, unknown>;
+interface CaptureResult {
+ requests: Array<{ url: string; method: string; body: RequestBody }>;
+ results: Array<{ content: string }>;
+ unexpectedFetches: string[];
+}
+let root: string;
+let captured: CaptureResult;
+
+beforeAll(async () => {
+ root = mkdtempSync(join(tmpdir(), "mcp-effort-request-"));
+ const home = join(root, "home");
+ const cwd = join(root, "cwd");
+ const claudeConfig = join(root, "claude-config");
+ for (const dir of [home, cwd, claudeConfig]) mkdirSync(dir, { recursive: true });
+
+ // The proxy singleton has no public shutdown/reset. Keep its listener and the
+ // fetch interception in a child process, never in Bun's shared test registry.
+ const source = `
+ import { readFileSync } from "node:fs";
+ import { homedir } from "node:os";
+ const requests = [];
+ const results = [];
+ const unexpectedFetches = [];
+ const response = readFileSync(${JSON.stringify(responsePath)}, "utf8");
+ const originalFetch = globalThis.fetch;
+ const interceptedFetch = async (input, init) => {
+ const url = new URL(typeof input === "string" ? input : input.url ?? input.href);
+ // Tokenizer WebAssembly is loaded from an in-memory data URI, not the network.
+ if (url.protocol === "data:") return originalFetch(input, init);
+ if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" ||
+ url.pathname !== "/v1/messages" || init?.method !== "POST") {
+ unexpectedFetches.push(url.href);
+ throw new Error("Unexpected fetch: " + url.href);
+ }
+ requests.push({ url: url.href, method: init.method, body: JSON.parse(init.body) });
+ return new Response(response, { headers: { "Content-Type": "text/event-stream" } });
+ };
+ interceptedFetch.preconnect = (url) => {
+ unexpectedFetches.push("preconnect:" + String(url));
+ throw new Error("No network preconnect is permitted");
+ };
+ globalThis.fetch = interceptedFetch;
+ try {
+ if (homedir() !== process.env.HOME) throw new Error("HOME was not isolated at startup");
+ const { runPromptViaProxy } = await import(${JSON.stringify(pathToFileURL(join(import.meta.dir, "mcp-server.ts")).href)});
+ results.push(await runPromptViaProxy(${JSON.stringify(model)}, ${JSON.stringify(prompt)}, ${JSON.stringify(system)}));
+ for (const level of ${JSON.stringify(LEVELS)}) {
+ results.push(await runPromptViaProxy(${JSON.stringify(model)}, ${JSON.stringify(prompt)}, ${JSON.stringify(system)}, level));
+ }
+ results.push(await runPromptViaProxy(${JSON.stringify(model)}, ${JSON.stringify(prompt)}));
+ await new Promise((resolve) => setTimeout(resolve, 25));
+ console.log("EFFORT_CAPTURE=" + JSON.stringify({ requests, results, unexpectedFetches }));
+ process.exit(0);
+ } catch (error) {
+ console.error(error);
+ console.error(JSON.stringify({ requests, unexpectedFetches }));
+ process.exit(1);
+ }
+ `;
+ const child = Bun.spawn([process.execPath, "--no-env-file", "-e", source], {
+ cwd,
+ env: {
+ PATH: process.env.PATH ?? "",
+ HOME: home,
+ USERPROFILE: home,
+ XDG_CONFIG_HOME: join(home, ".config"),
+ CLAUDE_CONFIG_DIR: claudeConfig,
+ ZDOTDIR: home,
+ TMPDIR: tmpdir(),
+ CLAUDISH_DISABLE_KEYCHAIN: "1",
+ CLAUDISH_DISABLE_OP: "1",
+ CLAUDISH_DISABLE_CATALOG_WARM: "1",
+ CLAUDISH_NO_PREDEFINED_ENDPOINTS: "1",
+ NO_COLOR: "1",
+ },
+ stdin: "ignore",
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ const timer = setTimeout(() => child.kill("SIGKILL"), 12_000);
+ try {
+ const [stdout, stderr, exitCode] = await Promise.all([
+ new Response(child.stdout).text(),
+ new Response(child.stderr).text(),
+ child.exited,
+ ]);
+ expect({ exitCode, stderr: exitCode === 0 ? "" : stderr }).toEqual({
+ exitCode: 0,
+ stderr: "",
+ });
+ const resultLine = stdout.split("\n").find((line) => line.startsWith("EFFORT_CAPTURE="));
+ expect(resultLine).toBeDefined();
+ captured = JSON.parse(resultLine!.slice("EFFORT_CAPTURE=".length)) as CaptureResult;
+ expect(captured.unexpectedFetches).toEqual([]);
+ expect(captured.requests).toHaveLength(LEVELS.length + 2);
+ expect(expectedText.length).toBeGreaterThan(0);
+ expect(captured.results).toHaveLength(captured.requests.length);
+ for (const result of captured.results) expect(result.content).toBe(expectedText);
+ } finally {
+ clearTimeout(timer);
+ if (child.exitCode === null) child.kill("SIGKILL");
+ await child.exited;
+ }
+}, 15_000);
+
+afterAll(() => {
+ if (root) rmSync(root, { recursive: true, force: true });
+});
+
+describe("runPromptViaProxy request effort at the proxy fetch boundary", () => {
+ test("omits the entire output_config key when effort is absent", () => {
+ expect(Object.hasOwn(captured.requests[0].body, "output_config")).toBe(false);
+ expect(captured.requests[0].body).toEqual({
+ model,
+ messages: [{ role: "user", content: prompt }],
+ system,
+ stream: true,
+ });
+ });
+
+ test.each([...LEVELS])("sends output_config.effort exactly as %s", (level) => {
+ const request = captured.requests[LEVELS.indexOf(level) + 1];
+ expect(new URL(request.url).pathname).toBe("/v1/messages");
+ expect(request.method).toBe("POST");
+ expect(request.body).toEqual({
+ model,
+ messages: [{ role: "user", content: prompt }],
+ system,
+ stream: true,
+ output_config: { effort: level },
+ });
+ });
+
+ test("does not retain output_config or system from an earlier request", () => {
+ expect(captured.requests.at(-1)?.body).toEqual({
+ model,
+ messages: [{ role: "user", content: prompt }],
+ stream: true,
+ });
+ expect(Object.hasOwn(captured.requests.at(-1)!.body, "output_config")).toBe(false);
+ });
+});
diff --git a/packages/cli/src/mcp-server.ts b/packages/cli/src/mcp-server.ts
index b5514881..cabb01be 100644
--- a/packages/cli/src/mcp-server.ts
+++ b/packages/cli/src/mcp-server.ts
@@ -9,16 +9,18 @@
* Run with: claudish --mcp (stdio transport)
*/
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
import { homedir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { EFFORT_LEVELS, type EffortLevel, isEffortLevel } from "./adapters/base-api-format.js";
import { searchCatalogModels } from "./adapters/model-catalog.js";
import { prehydrateCredentialsForSpawn } from "./auth/credentials/prehydrate.js";
import { setCredentialPromptRole } from "./auth/credentials/prompt-role.js";
+import { writeFileAtomic } from "./fs-atomic.js";
import { loadHooksOnce } from "./hooks/index.js";
import { type ProtocolStdout, isolateProtocolStdout } from "./hooks/output-capture.js";
import { initLogger, log } from "./logger.js";
@@ -37,7 +39,11 @@ import {
runPromptViaClaudeCode,
stopAllClaudeCodePrintChildren,
} from "./mcp/run-prompt-claude-code.js";
-import { type RecommendedModelsDoc, getRecommendedModels } from "./model-loader.js";
+import {
+ type RecommendedModelsDoc,
+ getRecommendedModels,
+ readLastRecommendedModels,
+} from "./model-loader.js";
// Imported for the predicate only. child-env's import-time bootstrap is a no-op here:
// a claudish MCP server is never the pane child (it carries no CLAUDISH_PANE_CWD).
import { inMcpSession } from "./pane/child-env.js";
@@ -57,8 +63,11 @@ import {
sockRootFor,
} from "./pane/index.js";
import { findAvailablePort } from "./port-manager.js";
+import { readAllModelsCache } from "./providers/all-models-cache.js";
+import { latestEffortRecommendations } from "./providers/effort-recommendations.js";
import { ensureEndpointsRegistered } from "./providers/endpoint-registration.js";
import { compareByReleaseDateDesc } from "./providers/model-ordering.js";
+import { isLocalProviderName, parseModelChain, parseModelSpec } from "./providers/model-parser.js";
import { nativeRouteFor } from "./providers/native-route.js";
import { renderOpFailureBlock } from "./providers/onepassword.js";
import {
@@ -69,7 +78,7 @@ import {
import { probeLink } from "./providers/probe-live.js";
import type { ProbeTarget } from "./providers/probe-runner.js";
import { createProxyServer } from "./proxy-server.js";
-import { nativeShortcutForVendor, renderRecommendedMarkdown } from "./recommended-listing.js";
+import { renderEffortTableMarkdown, renderRecommendedMarkdown } from "./recommended-listing.js";
import { sanitizeForReport } from "./redact.js";
import {
type ModelStatus,
@@ -228,17 +237,31 @@ async function loadAllModels(forceRefresh = false): Promise<any[]> {
if (!response.ok) throw new Error(`API returned ${response.status}`);
const data = await response.json();
const models = data.data || [];
- mkdirSync(CLAUDISH_CACHE_DIR, { recursive: true });
- writeFileSync(
- OPENROUTER_MODELS_CACHE_PATH,
- JSON.stringify({ lastUpdated: new Date().toISOString(), models }),
- "utf-8"
- );
+ try {
+ writeFileAtomic(
+ OPENROUTER_MODELS_CACHE_PATH,
+ JSON.stringify({ lastUpdated: new Date().toISOString(), models })
+ );
+ } catch (err) {
+ // The fetched list is still the answer; only the cache is lost.
+ log(
+ `[mcp] OpenRouter models cache write failed: ${err instanceof Error ? err.message : String(err)}`
+ );
+ }
return models;
- } catch {
- if (existsSync(OPENROUTER_MODELS_CACHE_PATH)) {
- const cacheData = JSON.parse(readFileSync(OPENROUTER_MODELS_CACHE_PATH, "utf-8"));
- return cacheData.models || [];
+ } catch (err) {
+ log(
+ `[mcp] OpenRouter models fetch failed: ${err instanceof Error ? err.message : String(err)}`
+ );
+ try {
+ if (existsSync(OPENROUTER_MODELS_CACHE_PATH)) {
+ const cacheData = JSON.parse(readFileSync(OPENROUTER_MODELS_CACHE_PATH, "utf-8"));
+ return cacheData.models || [];
+ }
+ } catch (cacheErr) {
+ log(
+ `[mcp] OpenRouter models cache unreadable: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}`
+ );
}
return [];
}
@@ -319,11 +342,16 @@ export function parseAnthropicSse(raw: string): {
* except on the Messages API, which requires one and gets the catalog's
* `maxOutputTokens`. No model limit is pinned here
* (ai-docs/architecture/wire.md "Output limit").
+ *
+ * `effort` goes out as `output_config.effort`, the field Claude Code itself sends,
+ * so step 5w maps it onto the connection's published levels as it does for Claude
+ * Code's own request.
*/
export async function runPromptViaProxy(
model: string,
prompt: string,
- systemPrompt?: string
+ systemPrompt?: string,
+ effort?: EffortLevel
): Promise<RunPromptResult> {
const proxy = await getProxy();
@@ -336,6 +364,9 @@ export async function runPromptViaProxy(
if (systemPrompt) {
body.system = systemPrompt;
}
+ if (effort) {
+ body.output_config = { effort };
+ }
const response = await fetch(`${proxy.url}/v1/messages`, {
method: "POST",
@@ -366,17 +397,21 @@ export async function runPromptViaProxy(
* caller's credential and an MCP call has none. Every other model, including the
* explicit `anthropic@claude-*` (metered), goes through the in-process proxy. The
* ORIGINAL model string is passed on; claudish's CLI owns alias normalisation.
+ *
+ * `effort` reaches only the proxy path: on the print path Claude Code sets the
+ * effort of its own Claude model.
*/
export async function runPrompt(
model: string,
prompt: string,
systemPrompt?: string,
- signal?: AbortSignal
+ signal?: AbortSignal,
+ effort?: EffortLevel
): Promise<RunPromptResult> {
if (nativeRouteFor(model) !== null) {
return runPromptViaClaudeCode(model, prompt, systemPrompt, { signal });
}
- return runPromptViaProxy(model, prompt, systemPrompt);
+ return runPromptViaProxy(model, prompt, systemPrompt, effort);
}
/** `run_prompt`'s success text: the answer, then a footer of token and auth lines. */
@@ -503,6 +538,179 @@ function fmtSize(n: number): string {
* Self-delimiting because MCP `resource_link` blocks arrive flattened into the
* text stream with no separator — a consumer must be able to see where this ends.
*/
+/**
+ * The MCP `effort` argument: undefined when absent, else a canonical level.
+ * Throws a message naming the levels on anything else.
+ */
+export function effortArg(value: unknown): EffortLevel | undefined {
+ if (value === undefined || value === null || value === "" || value === KEEP_EFFORT) {
+ return undefined;
+ }
+ if (isEffortLevel(value)) return value;
+ throw new Error(
+ `Invalid 'effort': ${JSON.stringify(value)}. Expected one of ${EFFORT_LEVELS.join(", ")} ` +
+ `or "${KEEP_EFFORT}" (list_models shows the recommended level per model and task type).`
+ );
+}
+
+/** The `effort` value that keeps Claude Code's own level, answering the clarification. */
+export const KEEP_EFFORT = "default";
+
+/**
+ * When a caller sent no effort, the recommended levels of the models that have
+ * any, by task type: `{model: {taskType: level}}`, keyed as the caller wrote the
+ * model. Undefined when none has a row, so a call with nothing to recommend is
+ * never stopped. A native Claude name is skipped: it ignores the effort.
+ */
+export function effortClarification(
+ specs: readonly string[],
+ efforts:
+ | Readonly<Record<string, Readonly<Record<string, { effort: string }>>>>
+ | undefined = latestEffortRecommendations()?.efforts
+): Record<string, Record<string, string>> | undefined {
+ if (!efforts) return undefined;
+ const out: Record<string, Record<string, string>> = {};
+ for (const spec of specs) {
+ if (nativeRouteFor(spec) !== null) continue;
+ const row = efforts[parseModelSpec(spec).model];
+ if (!row) continue;
+ out[spec] = Object.fromEntries(Object.entries(row).map(([task, rec]) => [task, rec.effort]));
+ }
+ return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * The answer that stops a call made with no effort: the caller knows its task,
+ * so it picks the column and calls again. Starts nothing.
+ */
+function needsEffortResult(
+ recommended: Record<string, Record<string, string>>,
+ how: string
+): { content: Array<{ type: "text"; text: string }>; isError: true } {
+ return {
+ content: [
+ {
+ type: "text" as const,
+ text:
+ `needs_effort: nothing was started. Map your task to one task type and call again ${how}.\n` +
+ `Recommended levels: ${JSON.stringify(recommended, null, 2)}`,
+ },
+ ],
+ isError: true,
+ };
+}
+
+/**
+ * The MCP `team` `efforts` argument: one canonical level per model, keyed by a
+ * string of `models` exactly. Undefined when absent; throws on a key that is
+ * not in `models` or a value that is not a level, so a typo never runs a slot
+ * at an effort the caller did not choose.
+ */
+export function modelEffortsArg(
+ value: unknown,
+ models: readonly string[]
+): Record<string, EffortLevel> | undefined {
+ if (value === undefined || value === null) return undefined;
+ if (typeof value !== "object" || Array.isArray(value)) {
+ throw new Error(`Invalid 'efforts': expected an object like {"<model>": "<level>"}.`);
+ }
+ const out: Record<string, EffortLevel> = {};
+ for (const [model, level] of Object.entries(value)) {
+ if (!models.includes(model)) {
+ throw new Error(
+ `Invalid 'efforts': ${JSON.stringify(model)} is not one of 'models' ` +
+ `(${models.join(", ")}). Keys must match a 'models' entry exactly.`
+ );
+ }
+ if (!isEffortLevel(level)) {
+ throw new Error(
+ `Invalid 'efforts' for ${model}: ${JSON.stringify(level)}. ` +
+ `Expected one of ${EFFORT_LEVELS.join(", ")}.`
+ );
+ }
+ out[model] = level;
+ }
+ return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** True when `id` is exactly a canonical model id of the cached cloud models catalog. */
+function isCanonicalCatalogModel(id: string): boolean {
+ return readAllModelsCache()?.entries.some((e) => e.modelId === id) ?? false;
+}
+
+/**
+ * A model spec as claudish routing must see it. The calling agent often writes a
+ * `provider@` the user never asked for (copied from a listing, or guessed), and
+ * that bypasses the user's routing: their providers, preferences and overrides.
+ * So the provider is removed unless the user required it (`required`), and only
+ * where the bare name routes: a single `provider@model` whose model part is a
+ * canonical model id of the cloud models catalog. Markers (`+pro`, `#fast`) stay.
+ * A chain, a local or custom-URL provider, legacy syntax or a wire id the catalog
+ * does not know as a model id (`kc@k3`) is returned unchanged.
+ */
+export function stripUnrequestedProvider(
+ spec: string,
+ required: boolean,
+ isCatalogModel: (id: string) => boolean = isCanonicalCatalogModel
+): string {
+ if (required || parseModelChain(spec).length !== 1) return spec;
+ const parsed = parseModelSpec(spec);
+ if (!parsed.isExplicitProvider || parsed.isLegacySyntax) return spec;
+ if (parsed.provider === "custom-url" || isLocalProviderName(parsed.provider)) return spec;
+ if (!isCatalogModel(parsed.model)) return spec;
+ return spec.slice(spec.indexOf("@") + 1);
+}
+
+/**
+ * The MCP `team` `user_required_provider` argument: the specs, exactly as in
+ * `models` or `judges`, whose provider the user named. Throws on anything else.
+ */
+export function userRequiredProvidersArg(
+ value: unknown,
+ specs: readonly string[]
+): ReadonlySet<string> {
+ if (value === undefined || value === null) return new Set();
+ if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+ throw new Error(`Invalid 'user_required_provider': expected an array of model specs.`);
+ }
+ for (const spec of value as string[]) {
+ if (!specs.includes(spec)) {
+ throw new Error(
+ `Invalid 'user_required_provider': ${JSON.stringify(spec)} is not one of the ` +
+ `models (${specs.join(", ")}). Entries must match a 'models' or 'judges' entry exactly.`
+ );
+ }
+ }
+ return new Set(value as string[]);
+}
+
+/** One `{from, to}` per spec whose provider was removed, for the tool's answer and the log. */
+export function strippedProviders(
+ specs: readonly string[],
+ required: ReadonlySet<string>,
+ isCatalogModel?: (id: string) => boolean
+): { specs: string[]; stripped: Array<{ from: string; to: string }> } {
+ const stripped: Array<{ from: string; to: string }> = [];
+ const out = specs.map((from) => {
+ const to = stripUnrequestedProvider(from, required.has(from), isCatalogModel);
+ if (to !== from) stripped.push({ from, to });
+ return to;
+ });
+ if (stripped.length > 0) {
+ log(`[mcp] provider removed: ${stripped.map((x) => `${x.from} -> ${x.to}`).join(", ")}`);
+ }
+ return { specs: out, stripped };
+}
+
+/** The note a tool answer carries when it removed a provider. */
+function strippedNote(stripped: ReadonlyArray<{ from: string; to: string }>): string | undefined {
+ if (stripped.length === 0) return undefined;
+ return (
+ `Provider removed so claudish routing decides: ${stripped.map((x) => `${x.from} -> ${x.to}`).join(", ")}. ` +
+ "Pass 'user_required_provider' only when the user named the provider."
+ );
+}
+
/**
* Build the flag list handed to every child Claude Code process.
*
@@ -794,7 +1002,13 @@ export function teamStatusAnswer(path: string, runId?: string): Record<string, u
let status: TeamStatus;
try {
status = getStatus(path);
- } catch {
+ } catch (err) {
+ // An absent status.json is normal before a run starts; a corrupt one is not.
+ if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
+ log(
+ `[team] unreadable status.json at ${path}: ${err instanceof Error ? err.message : String(err)}`
+ );
+ }
if (row) return { ...contractMeta(), run: row };
throw new ContractErrorException(
"unknown_run",
@@ -911,13 +1125,30 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
model: {
type: "string",
description:
- "Model name or model spec. A bare name auto-routes to the best provider; " +
- "'provider@model' pins the provider (e.g. 'google@gemini-4-argon', " +
- "'or@x-ai/grok-4.7'). A bare Claude name (claude-*, opus, sonnet, haiku) runs on " +
- "Claude Code's own login.",
+ "Model name. Pass the bare name (e.g. 'gemini-4-argon'): claudish routing picks " +
+ "the provider from the user's setup. A 'provider@' on a catalog model is removed " +
+ "unless 'user_required_provider' is true. A bare Claude name (claude-*, opus, " +
+ "sonnet, haiku) runs on Claude Code's own login.",
+ },
+ user_required_provider: {
+ type: "boolean",
+ description:
+ "True only when the USER named the provider ('use OpenRouter for it'): the " +
+ "'provider@model' spec is then sent as given.",
},
prompt: { type: "string", description: "The prompt to send to the model" },
system_prompt: { type: "string", description: "Optional system prompt" },
+ effort: {
+ type: "string",
+ enum: [...EFFORT_LEVELS, KEEP_EFFORT],
+ description:
+ "Reasoning effort for this request. Take it from list_models' " +
+ "'Recommended effort by task type' table: your task's column, this model's row. " +
+ "Omitted for a model that has a row, the call starts nothing and answers " +
+ `'needs_effort' with that row; "${KEEP_EFFORT}" keeps Claude Code's own level. ` +
+ "Mapped onto the levels the model's connection publishes. Ignored for a bare " +
+ "Claude name.",
+ },
},
required: ["model", "prompt"],
},
@@ -927,13 +1158,30 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
heartbeat: true,
handler: async (args, ctx) => {
try {
+ const { specs, stripped } = strippedProviders(
+ [args.model as string],
+ new Set(args.user_required_provider === true ? [args.model as string] : [])
+ );
+ // Keyed as the caller wrote the model, like team's 'efforts' keys.
+ const recommended =
+ args.effort === undefined ? effortClarification([args.model as string]) : undefined;
+ if (recommended) {
+ return needsEffortResult(
+ recommended,
+ `with effort: "<level>" (effort: "${KEEP_EFFORT}" keeps Claude Code's own)`
+ );
+ }
const result = await runPrompt(
- args.model as string,
+ specs[0],
args.prompt as string,
args.system_prompt as string | undefined,
- ctx.signal
+ ctx.signal,
+ effortArg(args.effort)
);
- return { content: [{ type: "text" as const, text: formatRunPromptResult(result) }] };
+ const text = [strippedNote(stripped), formatRunPromptResult(result)]
+ .filter(Boolean)
+ .join("\n\n");
+ return { content: [{ type: "text" as const, text }] };
} catch (error) {
const errMsg = error instanceof Error ? error.message : String(error);
return {
@@ -954,42 +1202,47 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
tools.push({
name: "list_models",
- description: "List recommended models for coding tasks",
+ description:
+ "List recommended models for coding tasks, and the catalog's recommended reasoning " +
+ "effort per model and task type (pass it as team 'efforts' or create_session / " +
+ "run_prompt 'effort')",
inputSchema: { type: "object" },
group: "low-level",
handler: async () => {
- let doc: RecommendedModelsDoc;
+ // A failed fetch falls back to the list last written to disk, of any
+ // generation, and says so; the reason goes to the log, never to stdout.
+ let doc: RecommendedModelsDoc | null = null;
+ let note = "";
try {
doc = await getRecommendedModels();
- } catch {
- return {
- content: [
- {
- type: "text" as const,
- text: "No recommended models found. Try search_models instead.",
- },
- ],
- };
+ if (!doc.models || doc.models.length === 0) {
+ log("[mcp] list_models: the recommended list is empty");
+ doc = null;
+ }
+ } catch (err) {
+ log(`[mcp] list_models: ${err instanceof Error ? err.message : String(err)}`);
}
- if (!doc.models || doc.models.length === 0) {
- return {
- content: [
- {
- type: "text" as const,
- text: "No recommended models found. Try search_models instead.",
- },
- ],
- };
+ if (!doc) {
+ doc = readLastRecommendedModels();
+ if (doc) {
+ note =
+ "_The live catalog could not be read; this list is from generation " +
+ `${doc.generationId ?? "unknown"}, the last one this machine stored._`;
+ log(
+ `[mcp] list_models: answered from stored generation ${doc.generationId ?? "unknown"}`
+ );
+ }
}
- return {
- content: [
- {
- type: "text" as const,
- text: renderRecommendedMarkdown(doc, nativeShortcutForVendor),
- },
- ],
- };
+ // getRecommendedModels wrote the sidecar on a fetch; an older one still
+ // shows the last generation this machine read.
+ const efforts = latestEffortRecommendations();
+ const effortTable = efforts ? renderEffortTableMarkdown(efforts.efforts) : "";
+ const listing = doc
+ ? renderRecommendedMarkdown(doc)
+ : "No recommended models found. Try search_models instead.";
+ const text = [note, listing, effortTable].filter(Boolean).join("\n\n");
+ return { content: [{ type: "text" as const, text }] };
},
});
@@ -1381,11 +1634,32 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
"so a native reviewer that never produced the required shape is reported " +
"EMPTY 'shape_mismatch' instead of silently succeeding.",
},
+ efforts: {
+ type: "object",
+ additionalProperties: { type: "string", enum: [...EFFORT_LEVELS] },
+ description:
+ "Reasoning effort per model for 'run' and 'run-and-judge', e.g. " +
+ '{"gpt-6-luna": "high", "kimi-k3": "max"}. Keys must match a \'models\' ' +
+ "entry exactly. Take each level from list_models' 'Recommended effort by task " +
+ "type' table: your task's column, the model's row. The slot pins that level on " +
+ "every request (claudish --effort-override); a model without an entry keeps " +
+ "Claude Code's own effort. Omitted while a model has a row, nothing starts and " +
+ "the answer is 'needs_effort' with the rows; {} keeps Claude Code's own for all.",
+ },
judges: {
type: "array",
items: { type: "string" },
description: "Model IDs to use as judges (default: same as runners)",
},
+ user_required_provider: {
+ type: "array",
+ items: { type: "string" },
+ description:
+ "The 'models' or 'judges' entries whose provider the USER named ('run Kimi on " +
+ "OpenRouter'), exactly as written there. Every other 'provider@' on a catalog " +
+ "model is removed so claudish routing picks the provider from the user's setup; " +
+ "pass bare names unless the user asked for a provider.",
+ },
input_file: {
type: "string",
description:
@@ -1474,8 +1748,24 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
throw new Error(`Unknown mode: ${mode}`);
const path = args.path;
if (typeof path !== "string" || !path) throw new Error(`'path' is required for '${mode}'`);
- const models = args.models as string[] | undefined;
- const judges = args.judges as string[] | undefined;
+ const givenModels = args.models as string[] | undefined;
+ const givenJudges = args.judges as string[] | undefined;
+ const requiredProviders = userRequiredProvidersArg(args.user_required_provider, [
+ ...(givenModels ?? []),
+ ...(givenJudges ?? []),
+ ]);
+ const modelStrip = givenModels
+ ? strippedProviders(givenModels, requiredProviders)
+ : undefined;
+ const judgeStrip = givenJudges
+ ? strippedProviders(givenJudges, requiredProviders)
+ : undefined;
+ const models = modelStrip?.specs;
+ const judges = judgeStrip?.specs;
+ const providerNote = strippedNote([
+ ...(modelStrip?.stripped ?? []),
+ ...(judgeStrip?.stripped ?? []),
+ ]);
// `input_file` is the preferred form: a team prompt is usually a long
// brief, and inline text is echoed in full in the caller's terminal.
// Accepting both would silently pick one and discard the other, which is
@@ -1497,10 +1787,22 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
const resolved = validateSessionPath(path);
+ // Keys name the models as the caller wrote them; the slots run the stripped specs.
+ const givenEfforts = givenModels ? modelEffortsArg(args.efforts, givenModels) : undefined;
+ const efforts = givenEfforts
+ ? Object.fromEntries(
+ Object.entries(givenEfforts).map(([m, level]) => [
+ models?.[givenModels?.indexOf(m) ?? -1] ?? m,
+ level,
+ ])
+ )
+ : undefined;
+
const runOpts = {
requirePattern,
minOutputBytes,
claudeFlags: childFlags,
+ efforts,
onProgress: (u: { phase: "running" | "settled" }) => {
// A state change is real news, so refresh the client's idle timer at
// that moment as well as on the periodic tick. Short phase string only:
@@ -1516,6 +1818,21 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
return existsSync(existing) ? readFileSync(existing, "utf-8") : undefined;
};
+ if (
+ (mode === "run" || mode === "run-and-judge") &&
+ givenModels &&
+ args.efforts === undefined
+ ) {
+ // Keyed as the caller wrote the models: that is how 'efforts' keys must read.
+ const recommended = effortClarification(givenModels);
+ if (recommended) {
+ return needsEffortResult(
+ recommended,
+ `with efforts: {"<model>": "<level>"} (efforts: {} keeps Claude Code's own for every model)`
+ );
+ }
+ }
+
switch (mode) {
case "run": {
if (!models?.length) throw new Error("'models' is required for 'run' mode");
@@ -1596,6 +1913,7 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
cancel: `team(mode:"cancel", path:"${p}", slot:"<id>")`,
judge: `team(mode:"judge", path:"${p}") once every slot has finished`,
},
+ ...(providerNote ? { provider_note: providerNote } : {}),
note:
"Every slot has taken its prompt or failed to. Nothing terminates a " +
"working slot on a timer: `status` reports each slot's state, " +
@@ -1611,7 +1929,8 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
}
case "judge": {
const verdict = await judgeResponses(resolved, { judges, claudeFlags: childFlags });
- return { content: [{ type: "text" as const, text: JSON.stringify(verdict, null, 2) }] };
+ const out = providerNote ? { ...verdict, provider_note: providerNote } : verdict;
+ return { content: [{ type: "text" as const, text: JSON.stringify(out, null, 2) }] };
}
case "run-and-judge": {
if (!models?.length) throw new Error("'models' is required for 'run-and-judge' mode");
@@ -1631,7 +1950,16 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
content: [
{
type: "text" as const,
- text: JSON.stringify({ ...verdict, run_id: handle.runId, run }, null, 2),
+ text: JSON.stringify(
+ {
+ ...verdict,
+ run_id: handle.runId,
+ run,
+ ...(providerNote ? { provider_note: providerNote } : {}),
+ },
+ null,
+ 2
+ ),
},
],
};
@@ -1820,7 +2148,15 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
model: {
type: "string",
description:
- "Model identifier (e.g., '[email protected]', 'x-ai/grok-code-fast-1')",
+ "Model name. Pass the bare name (e.g. 'gpt-6.1-sol'): claudish routing picks the " +
+ "provider from the user's setup. A 'provider@' on a catalog model is removed " +
+ "unless 'user_required_provider' is true.",
+ },
+ user_required_provider: {
+ type: "boolean",
+ description:
+ "True only when the USER named the provider: the 'provider@model' spec is then " +
+ "used as given.",
},
prompt: {
type: "string",
@@ -1847,6 +2183,16 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
"Flags the pane owns or that only work in print mode are refused. NOTE: split on " +
"whitespace, so a flag VALUE containing spaces cannot be expressed here.",
},
+ effort: {
+ type: "string",
+ enum: [...EFFORT_LEVELS, KEEP_EFFORT],
+ description:
+ "Reasoning effort for the whole session. Take it from list_models' " +
+ "'Recommended effort by task type' table: your task's column, this model's row. " +
+ "Pinned on every request (claudish --effort-override), over one in claude_flags. " +
+ "Omitted for a model that has a row, nothing starts and the answer is " +
+ `'needs_effort' with that row; "${KEEP_EFFORT}" keeps Claude Code's own level.`,
+ },
work_dir: {
type: "string",
description: "Working directory for the session (default: current directory)",
@@ -1867,6 +2213,8 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
handler: async (args) => {
try {
const claudishFlags = buildChildClaudeFlags(args.agent, args.claude_flags) ?? [];
+ const effort = effortArg(args.effort);
+ if (effort) claudishFlags.push("--effort-override", effort);
// Refusals first, before any credential work: reserved or positional flags, then
// a missing magmux (its message starts with the code word). An unknown --agent is
// refused by the child itself, before any model request (D11).
@@ -1887,7 +2235,19 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
// reads project-local config relative to process.cwd(), so the parent
// would decide with the wrong project's rules. process.chdir() is not
// an option — it is process-global and races concurrent calls.
- const requestedModel = args.model as string;
+ const { specs, stripped } = strippedProviders(
+ [args.model as string],
+ new Set(args.user_required_provider === true ? [args.model as string] : [])
+ );
+ const requestedModel = specs[0];
+ const recommended =
+ args.effort === undefined ? effortClarification([args.model as string]) : undefined;
+ if (recommended) {
+ return needsEffortResult(
+ recommended,
+ `with effort: "<level>" (effort: "${KEEP_EFFORT}" keeps Claude Code's own)`
+ );
+ }
const workDir = args.work_dir as string | undefined;
const plan = await prehydrateCredentialsForSpawn([requestedModel], {
@@ -1921,6 +2281,9 @@ function defineTools(sessionManager: SessionManager, nested: boolean): ToolDefin
text: JSON.stringify({
session_id: sessionId,
state: sessionManager.getSession(sessionId).state,
+ ...(stripped.length > 0
+ ? { model: requestedModel, note: strippedNote(stripped) }
+ : {}),
}),
},
],
@@ -2283,8 +2646,18 @@ async function main() {
// loader loads no user hook module in this process.
const iso: ProtocolStdout = isolateProtocolStdout();
- // The debug log is also where hook output and diverted stdout writes go.
- if (mcpDebugLogEnabled(process.argv.slice(2), process.env)) initLogger(true, "debug", true);
+ // The always-on structural log (~/.claudish/logs/claudish-mcp_*.log, never
+ // stdout) records why a tool answered from a fallback; `--log-off` disables it,
+ // as for every other claudish run. The debug log is also where hook output and
+ // diverted stdout writes go.
+ const argv = process.argv.slice(2);
+ initLogger(
+ mcpDebugLogEnabled(argv, process.env),
+ "debug",
+ argv.includes("--log-off"),
+ "claudish-mcp",
+ 500
+ );
if (!iso.active) log(`[mcp] protocol stdout not isolated: ${iso.reason ?? "unknown"}`);
// Session hooks need the engine without a proxy, so loading starts now, in the
@@ -2414,7 +2787,10 @@ async function main() {
// pane's own sweep (ensureSwept in startPaneSession) is this one, not a second `ps`.
// A nested server registers no session tools and never spawns a pane, so it has
// nothing to sweep.
- if (!nested) void ensureSwept(sockRootFor()).catch(() => undefined);
+ if (!nested)
+ void ensureSwept(sockRootFor()).catch((err: unknown) =>
+ log(`[mcp] stale pane sweep failed: ${err instanceof Error ? err.message : String(err)}`)
+ );
}
/**
diff --git a/packages/cli/src/team-orchestrator-settle.contract.test.ts b/packages/cli/src/team-orchestrator-settle.contract.test.ts
index 2a81dd13..c3e7c10c 100644
--- a/packages/cli/src/team-orchestrator-settle.contract.test.ts
+++ b/packages/cli/src/team-orchestrator-settle.contract.test.ts
@@ -50,9 +50,9 @@ beforeEach(() => {
});
afterEach(async () => {
try {
- chmodSync(join(teamDir, "status.json"), 0o644);
+ chmodSync(teamDir, 0o755);
} catch {
- // no status.json in this test
+ // no team directory in this test
}
const report = await finishPaneTest(panes);
layout.cleanup();
@@ -153,9 +153,9 @@ describe.skipIf(!MAGMUX)(
(err: unknown) => err
);
// The fault (§20.2, replacing the spawn seam's throw): once slot 1's pane exists — its
- // pane record is written before anything is spawned — status.json turns read-only,
- // inside the 300 ms boot stagger, so slot 2's STARTING write throws EACCES. (The file,
- // not the directory: an overwrite in place needs write permission on the file.)
+ // pane record is written before anything is spawned — the team directory turns read-only,
+ // inside the 300 ms boot stagger, so slot 2's atomic STARTING status write throws EACCES
+ // when it cannot create status.json.tmp.<pid>.
await waitFor(
() => {
const recs = join(panes.sockRoot, "panes");
@@ -163,7 +163,7 @@ describe.skipIf(!MAGMUX)(
},
{ what: "slot 1's pane record", timeoutMs: 5_000, intervalMs: 5 }
);
- chmodSync(join(teamDir, "status.json"), 0o444);
+ chmodSync(teamDir, 0o555);
const thrown = await run;
// was: slot 1 got SIGTERM. Now: every started pane is reaped (no process, socket or
diff --git a/packages/cli/src/team-orchestrator.ts b/packages/cli/src/team-orchestrator.ts
index 30b4b749..9c434cc9 100644
--- a/packages/cli/src/team-orchestrator.ts
+++ b/packages/cli/src/team-orchestrator.ts
@@ -13,6 +13,7 @@ import {
import { basename, dirname, join, resolve, sep } from "node:path";
import { type SpawnPlan, prehydrateCredentialsForSpawn } from "./auth/credentials/prehydrate.js";
import { ENV } from "./config.js";
+import { writeFileAtomic } from "./fs-atomic.js";
import { UPSTREAM_ERROR_LOG_ENV } from "./handlers/shared/upstream-error-capture.js";
import type { HookEngine } from "./hooks/engine.js";
import { loadHooksOnce } from "./hooks/index.js";
@@ -26,6 +27,7 @@ import {
reportOwnerWithoutHooks,
sessionHooksNeedBinding,
} from "./hooks/session/binding.js";
+import { log } from "./logger.js";
import {
type Accounting,
type CaptureResult,
@@ -167,6 +169,12 @@ export interface TeamStatus {
export interface TeamRunOptions {
claudeFlags?: string[]; // extra flags passed to child claudish (checked by checkChildFlags)
+ /**
+ * Reasoning effort per model, keyed by the model string as the run's models give
+ * it. A slot with an entry gets `--effort-override <level>` after `claudeFlags`, so
+ * it wins over one there and its proxy pins that level on every request.
+ */
+ efforts?: Readonly<Record<string, string>>;
onStatusChange?: (id: string, status: ModelStatus) => void;
/**
* Opt-in stub threshold: below this many answer bytes a settled slot is recorded
@@ -1194,7 +1202,7 @@ export function setupSession(sessionPath: string, models: string[], input?: stri
])
),
};
- writeFileSync(join(sessionPath, "status.json"), JSON.stringify(status, null, 2), "utf-8");
+ writeFileAtomic(join(sessionPath, "status.json"), JSON.stringify(status, null, 2));
return manifest;
}
@@ -1352,7 +1360,7 @@ async function startModelsIn(
statusCache.models[id] = { ...statusCache.models[id], ...update } as ModelStatus;
}
function flushStatus(): void {
- writeFileSync(statusPath, JSON.stringify(statusCache, null, 2), "utf-8");
+ writeFileAtomic(statusPath, JSON.stringify(statusCache, null, 2));
}
function updateModelStatus(id: string, update: Partial<ModelStatus>): void {
if (aborting) return;
@@ -1377,8 +1385,12 @@ async function startModelsIn(
let run: LiveTeamRun | null = null;
const errorLogPathOf = (id: string) => join(path, "errors", `${id}.log`);
const upstreamLogOf = (id: string) => upstreamLogPath(path, id);
+ const flagsOf = (e: SlotEntry): string[] => {
+ const effort = opts.efforts?.[e.model];
+ return effort ? [...claudeFlags, "--effort-override", effort] : claudeFlags;
+ };
const commandOf = (e: SlotEntry) =>
- ["claudish", "-i", "--model", e.spawnModel ?? e.model, "-y", "--quiet", ...claudeFlags].join(
+ ["claudish", "-i", "--model", e.spawnModel ?? e.model, "-y", "--quiet", ...flagsOf(e)].join(
" "
);
@@ -1592,7 +1604,7 @@ async function startModelsIn(
session = await startPaneSession({
kind: "t",
label: e.id,
- callerFlags: claudeFlags,
+ callerFlags: flagsOf(e),
spawnModel: e.spawnModel ?? e.model,
cwd,
sessionUuid: uuid,
@@ -1855,8 +1867,12 @@ async function startModelsIn(
// the `onProgress` convention: a consumer can never fail the run.
try {
opts.onSettled?.(statusCache);
- } catch {
- // A settle consumer must never be able to fail the run.
+ } catch (err) {
+ // A settle consumer must never be able to fail the run, but its failure
+ // leaves the run record unended, so it is logged.
+ log(
+ `[team] onSettled failed for ${path}: ${err instanceof Error ? err.message : String(err)}`
+ );
}
resolveSettled();
}
@@ -1864,7 +1880,9 @@ async function startModelsIn(
})();
// A caller that only polls never touches `done`. Without this an unobserved rejection
// would take down the MCP server, which hosts every other session too.
- done.catch(() => {});
+ done.catch((err: unknown) =>
+ log(`[team] run failed at ${path}: ${err instanceof Error ? err.message : String(err)}`)
+ );
return {
runId,
@@ -1985,8 +2003,13 @@ export function readTeamStatus(sessionPath: string): TeamStatus {
) {
return parsed;
}
- } catch {
- // Unreadable or partial — `status.json` writes are not atomic.
+ } catch (err) {
+ // status.json is written atomically, so anything but its absence is a fault.
+ if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
+ log(
+ `[team] unreadable status.json at ${sessionPath}: ${err instanceof Error ? err.message : String(err)}`
+ );
+ }
}
return { startedAt: new Date().toISOString(), models: {} };
}
@@ -2095,7 +2118,11 @@ export function parseJudgeVotes(judgePath: string, responseIds: string[]): VoteR
let content: string;
try {
content = readFileSync(join(judgePath, file), "utf-8");
- } catch {
+ } catch (err) {
+ // This judge's votes are dropped from the verdict; say so.
+ log(
+ `[team] judge answer ${file} unreadable: ${err instanceof Error ? err.message : String(err)}`
+ );
continue;
}
diff --git a/packages/cli/src/team-run-settles-once.test.ts b/packages/cli/src/team-run-settles-once.test.ts
index c0ee7173..5afb13d8 100644
--- a/packages/cli/src/team-run-settles-once.test.ts
+++ b/packages/cli/src/team-run-settles-once.test.ts
@@ -62,7 +62,7 @@ beforeEach(() => {
afterEach(async () => {
for (const dir of readdirSync(tempRoot)) {
try {
- chmodSync(join(tempRoot, dir, "status.json"), 0o644);
+ chmodSync(join(tempRoot, dir), 0o755);
} catch {
// not a team dir
}
@@ -87,8 +87,8 @@ describe("team run record settles once", () => {
settledCalls++;
},
}).catch((err: unknown) => err);
- // The fault: slot 1's pane record exists, so status.json turns read-only and slot
- // 2's STARTING write throws (was: slot 2's spawn threw EMFILE).
+ // The fault: slot 1's pane record exists, so the team directory turns read-only and slot
+ // 2's atomic STARTING status write cannot create its temp file (was: slot 2's spawn threw EMFILE).
await waitUntil(
() => {
const recs = join(panes.sockRoot, "panes");
@@ -98,7 +98,7 @@ describe("team run record settles once", () => {
5_000,
5
);
- chmodSync(join(sessionPath, "status.json"), 0o444);
+ chmodSync(sessionPath, 0o555);
const error = await run;
expect((error as NodeJS.ErrnoException).code).toBe("EACCES");
diff --git a/packages/cli/src/team-start-failure.test.ts b/packages/cli/src/team-start-failure.test.ts
index 18208350..15f6d53b 100644
--- a/packages/cli/src/team-start-failure.test.ts
+++ b/packages/cli/src/team-start-failure.test.ts
@@ -40,7 +40,7 @@ beforeEach(() => {
afterEach(async () => {
try {
- chmodSync(join(sessionPath, "status.json"), 0o644);
+ chmodSync(sessionPath, 0o755);
} catch {
// not created
}
@@ -73,8 +73,8 @@ describe.skipIf(!MAGMUX)("team spawn-loop failure", () => {
5_000
);
await Bun.sleep(600); // its module loads and boot() installs the trap
- // The next slot's STARTING write now throws.
- chmodSync(join(sessionPath, "status.json"), 0o444);
+ // The next slot's atomic STARTING status write cannot create its temp file.
+ chmodSync(sessionPath, 0o555);
const error = await run;
expect(error).toBeInstanceOf(Error);