@flumecode/runner 0.19.0 → 0.21.0-beta.1

package/dist/cli.js

@@ -26,8 +26,8 @@ function writeConfig(config) {
 }
 
 // src/run.ts
-import { existsSync as existsSync3 } from "node:fs";
-import { join as join4 } from "node:path";
+import { existsSync as existsSync4 } from "node:fs";
+import { join as join5 } from "node:path";
 
 // src/version.ts
 import { readFileSync as readFileSync2 } from "node:fs";
@@ -203,51 +203,59 @@ var WIDGET_TOOL_NAMES = [
 ];
 var optionsSchema = z.array(z.string().min(1)).min(2).max(8).describe("2\u20138 short, distinct choices for the user to pick from. " + WIDGET_LANGUAGE_HINT);
 var TAIL = "Do NOT add an 'Other' or 'None of these' catch-all \u2014 the UI always offers an 'Other' free-text option automatically. " + WIDGET_LANGUAGE_HINT + " After calling this, END YOUR TURN and wait: the user's answer arrives as their next message and starts a fresh run.";
+var singleSelectShape = {
+  question: z.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
+  body: z.string().optional().describe(
+    "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
+  ),
+  options: optionsSchema
+};
+var multiSelectShape = {
+  question: z.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
+  body: z.string().optional().describe(
+    "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
+  ),
+  options: optionsSchema
+};
+function buildSingleSelectWidget(args) {
+  return {
+    id: randomUUID(),
+    type: "single_select",
+    question: args.question,
+    body: args.body,
+    options: args.options.map((label) => ({ id: randomUUID(), label })),
+    selectedOptionId: null,
+    customAnswer: null
+  };
+}
+function buildMultiSelectWidget(args) {
+  return {
+    id: randomUUID(),
+    type: "multi_select",
+    question: args.question,
+    body: args.body,
+    options: args.options.map((label) => ({ id: randomUUID(), label })),
+    selectedOptionIds: null,
+    customAnswer: null
+  };
+}
 function createWidgetTooling() {
   const collected = [];
   const singleSelect = tool(
     SINGLE_SELECT,
     "Ask the user a single-select (radio-button) question \u2014 exactly one answer. Use this for a genuine either/or choice (competing approaches, scope decisions, yes/no) instead of writing the options as prose. " + TAIL,
-    {
-      question: z.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
-      body: z.string().optional().describe(
-        "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
-      ),
-      options: optionsSchema
-    },
+    singleSelectShape,
     async (args) => {
-      collected.push({
-        id: randomUUID(),
-        type: "single_select",
-        question: args.question,
-        body: args.body,
-        options: args.options.map((label) => ({ id: randomUUID(), label })),
-        selectedOptionId: null,
-        customAnswer: null
-      });
+      collected.push(buildSingleSelectWidget(args));
       return widgetPosted("single-select");
     }
   );
   const multiSelect = tool(
     MULTI_SELECT,
     "Ask the user a multi-select (checkbox) question \u2014 they may pick any number of options, including none of the presets if they use 'Other'. Use this for 'select all that apply' questions (which features to include, which files to touch). " + TAIL,
-    {
-      question: z.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
-      body: z.string().optional().describe(
-        "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
-      ),
-      options: optionsSchema
-    },
+    multiSelectShape,
     async (args) => {
-      collected.push({
-        id: randomUUID(),
-        type: "multi_select",
-        question: args.question,
-        body: args.body,
-        options: args.options.map((label) => ({ id: randomUUID(), label })),
-        selectedOptionIds: null,
-        customAnswer: null
-      });
+      collected.push(buildMultiSelectWidget(args));
       return widgetPosted("multi-select");
     }
   );
@@ -321,6 +329,9 @@ var planInputSchema = {
   rootCause: z2.string().optional().describe(
     'For bug fixes (scope === "fix"): the underlying cause of the bug \u2014 the specific code, logic, or condition that produces the incorrect behavior, not just the symptom. Required when scope is "fix"; omit for all other scopes. ' + INLINE_CODE_HINT
   ),
+  motivation: z2.string().optional().describe(
+    "Why the user is making this request \u2014 the underlying motivation or problem the change addresses. Fill this especially when the request content/context does NOT already state the why (ask the user in the Clarify phase); omit when there is no additional motivation to record. Useful for future understanding of the system. " + INLINE_CODE_HINT
+  ),
   assumptions: z2.array(z2.string()).describe("Anything decided during planning, including unanswered defaults."),
   requirements: z2.array(z2.string().min(1)).min(1).describe(
     "Required, human-readable statements of what this change must accomplish and why, in plain language a non-technical reader can follow. Distinct from acceptanceCriteria: requirements explain intent/rationale; acceptance criteria are the machine-checkable proof. At least 1 required. " + INLINE_CODE_HINT
@@ -351,6 +362,11 @@ function renderPlan(plan) {
   lines2.push(`**Scope** \u2014 \`${plan.scope}\``);
   lines2.push("");
   lines2.push(`**Goal** \u2014 ${plan.goal}`);
+  if (plan.motivation && plan.motivation.trim().length > 0) {
+    lines2.push("");
+    lines2.push("## Motivation");
+    lines2.push(plan.motivation);
+  }
   if (plan.assumptions.length > 0) {
     lines2.push("");
     lines2.push("**Assumptions**");
@@ -426,7 +442,7 @@ function createPlanTooling() {
   let renderedPlans = null;
   const submitPlan = tool2(
     SUBMIT_PLAN,
-    `Submit ALL your plans in a single call \u2014 one entry per plan; each becomes its own independently-acceptable Accept-as-plan draft. Do NOT call submit_plan more than once. acceptanceCriteria is required in each plan and must contain at least 2 observable, verifiable conditions. The 'title' field names each specific plan \u2014 make it concise and distinct from the request title and from sibling plan titles. requirements is required in each plan: at least 1 plain-language statement of what the change must accomplish and why (human-readable intent), separate from the machine-checkable acceptanceCriteria. When a plan's scope is "fix", rootCause is required: a non-empty explanation of the underlying cause of the bug (not just the symptom). `,
+    `Submit ALL your plans in a single call \u2014 one entry per plan; each becomes its own independently-acceptable Accept-as-plan draft. Do NOT call submit_plan more than once. acceptanceCriteria is required in each plan and must contain at least 2 observable, verifiable conditions. The 'title' field names each specific plan \u2014 make it concise and distinct from the request title and from sibling plan titles. requirements is required in each plan: at least 1 plain-language statement of what the change must accomplish and why (human-readable intent), separate from the machine-checkable acceptanceCriteria. When a plan's scope is "fix", rootCause is required: a non-empty explanation of the underlying cause of the bug (not just the symptom). motivation is optional: the user's stated or asked-for reason for the request. `,
     submitPlanInputSchema,
     async (args) => {
       const parsed = submitPlanSchema.parse(args);
@@ -709,6 +725,87 @@ async function runClaudeCode(opts) {
   return { text: finalText, widgets: collected, plans: getPlans(), report: getReport() };
 }
 
+// src/codex.ts
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+var MCP_ENTRY = fileURLToPath3(new URL("./mcp-stdio.js", import.meta.url));
+async function runCodex(opts) {
+  const tmpDir = mkdtempSync(join2(tmpdir(), "flume-codex-"));
+  const outFile = join2(tmpDir, "flume-mcp.jsonl");
+  writeFileSync2(outFile, "");
+  const child = spawn(
+    "codex",
+    [
+      "exec",
+      "--cwd",
+      opts.cwd,
+      "-c",
+      `mcp_servers.flume.command=node`,
+      "-c",
+      `mcp_servers.flume.args=${JSON.stringify([MCP_ENTRY])}`,
+      opts.prompt
+    ],
+    {
+      cwd: opts.cwd,
+      env: { ...process.env, FLUME_MCP_OUTPUT: outFile },
+      // stdin is inherited (codex may read from it), stdout/stderr are piped for streaming
+      stdio: ["inherit", "pipe", "pipe"]
+    }
+  );
+  child.stdout?.on("data", (chunk) => {
+    const text = chunk.toString();
+    process.stdout.write(text);
+    logEvent("agent", text);
+  });
+  child.stderr?.on("data", (chunk) => {
+    const text = chunk.toString();
+    process.stderr.write(text);
+    logEvent("agent", text);
+  });
+  const onAbort = () => {
+    child.kill("SIGTERM");
+  };
+  opts.abortController?.signal.addEventListener("abort", onAbort, { once: true });
+  await new Promise((resolve, reject) => {
+    child.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        reject(
+          new Error(
+            "codex CLI not found. Install it with `npm install -g @openai/codex` and log in before running plan-mode jobs with an openai agent."
+          )
+        );
+      } else {
+        reject(err);
+      }
+    });
+    child.on("close", () => resolve());
+  });
+  opts.abortController?.signal.removeEventListener("abort", onAbort);
+  if (opts.abortController?.signal.aborted) {
+    throw new Error("Run canceled by user");
+  }
+  const raw = existsSync2(outFile) ? readFileSync3(outFile, "utf8") : "";
+  const records = raw.split("\n").filter(Boolean).map(parseJsonLine).filter((r) => r !== null);
+  const plans = records.filter((r) => r.kind === "plans").flatMap((r) => r.plans ?? []);
+  const widgets = records.filter((r) => r.kind === "widget").map((r) => r.widget);
+  return {
+    text: "",
+    widgets,
+    plans: plans.length > 0 ? plans : null,
+    report: null
+  };
+}
+function parseJsonLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
 // src/health.ts
 import { query as query2 } from "@anthropic-ai/claude-agent-sdk";
 var PROBE_TIMEOUT_MS = 6e4;
@@ -757,19 +854,45 @@ function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
+// src/models.ts
+var MODEL_ROSTER = {
+  anthropic: { think: "opus", execute: "sonnet" },
+  openai: { think: "gpt-5.5", execute: "gpt-5.4-mini" }
+  // TODO: confirm vs `codex`
+};
+function rosterFor(provider) {
+  return MODEL_ROSTER[provider ?? "anthropic"] ?? MODEL_ROSTER.anthropic;
+}
+function renderRosterBlock(provider) {
+  const r = rosterFor(provider);
+  return [
+    "# Model tiers",
+    "When a skill tells you to run a subagent on a named model tier, pass the matching",
+    "concrete model id as the Task `model` argument. Use the id exactly; never pass the",
+    "tier name itself.",
+    `- \`think\`   -> \`${r.think}\`  (planning, review, high-level reasoning)`,
+    `- \`execute\` -> \`${r.execute}\`  (writing code from the plan; fast & cheap)`
+  ].join("\n");
+}
+
 // src/rules.ts
-import { readFileSync as readFileSync3 } from "node:fs";
-import { join as join2 } from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
-var RULES_DIR = fileURLToPath3(new URL("../skills-plugin/rules", import.meta.url));
+import { readFileSync as readFileSync4 } from "node:fs";
+import { join as join3 } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
+var RULES_DIR = fileURLToPath4(new URL("../skills-plugin/rules", import.meta.url));
 function loadRule(name) {
-  const raw = readFileSync3(join2(RULES_DIR, `${name}.md`), "utf8");
+  const raw = readFileSync4(join3(RULES_DIR, `${name}.md`), "utf8");
   return stripFrontMatter(raw).trim();
 }
 function stripFrontMatter(raw) {
   const match = raw.match(/^---\n.*?\n---\n/s);
   return match ? raw.slice(match[0].length) : raw;
 }
+var SKILLS_DIR = fileURLToPath4(new URL("../skills-plugin/skills", import.meta.url));
+function loadSkill(name) {
+  const raw = readFileSync4(join3(SKILLS_DIR, name, "SKILL.md"), "utf8");
+  return stripFrontMatter(raw).trim();
+}
 
 // src/prompt.ts
 function appendRule(lines2, intro, ruleName) {
@@ -804,6 +927,7 @@ function buildPrompt(ctx) {
     LANGUAGE_DIRECTIVE
   ];
   if (ctx.permissionMode !== "plan") {
+    lines2.push("", renderRosterBlock(ctx.provider));
     lines2.push(
       "",
       "These coding guidelines apply to all code produced in this run:",
@@ -835,6 +959,8 @@ function buildRevisePrompt(ctx) {
     widgets,
     LANGUAGE_DIRECTIVE,
     "",
+    renderRosterBlock(ctx.provider),
+    "",
     "These coding guidelines apply to all code produced in this run:",
     "",
     loadRule("coding-guideline"),
@@ -992,6 +1118,12 @@ function buildReleasePrompt(ctx, baseChecks) {
   );
   return lines2.join("\n");
 }
+function buildCodexPrompt(ctx) {
+  const skill = loadSkill("request-to-plan");
+  return ["# request-to-plan skill (follow these instructions)", skill, "", buildPrompt(ctx)].join(
+    "\n"
+  );
+}
 function buildInitPrompt(ctx) {
   return [
     `You are "${ctx.agentName}" initializing FlumeCode for the repository ${ctx.repo.fullName}, checked out in your current working directory.`,
@@ -1008,10 +1140,10 @@ function jobTitle(ctx) {
 
 // src/workspace.ts
 import { execFile } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 import { mkdtemp, readdir, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join as join3 } from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join4 } from "node:path";
 import { promisify } from "node:util";
 var exec = promisify(execFile);
 var WORKSPACE_PREFIX = "flume-runner-";
@@ -1037,11 +1169,11 @@ function cloneUrl(ctx) {
   return `https://x-access-token:${cloneToken}@github.com/${owner}/${name}.git`;
 }
 function detectPackageManager(dir) {
-  if (!existsSync2(join3(dir, "package.json"))) return null;
-  if (existsSync2(join3(dir, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync2(join3(dir, "yarn.lock"))) return "yarn";
-  if (existsSync2(join3(dir, "package-lock.json"))) return "npm";
-  if (existsSync2(join3(dir, "bun.lockb"))) return "bun";
+  if (!existsSync3(join4(dir, "package.json"))) return null;
+  if (existsSync3(join4(dir, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync3(join4(dir, "yarn.lock"))) return "yarn";
+  if (existsSync3(join4(dir, "package-lock.json"))) return "npm";
+  if (existsSync3(join4(dir, "bun.lockb"))) return "bun";
   return "npm";
 }
 async function installDependencies(dir) {
@@ -1067,13 +1199,13 @@ async function installDependencies(dir) {
   }
 }
 async function makeWorkspace() {
-  return mkdtemp(join3(tmpdir(), WORKSPACE_PREFIX));
+  return mkdtemp(join4(tmpdir2(), WORKSPACE_PREFIX));
 }
 var MAX_WORKSPACES = 8;
 var workspaceRegistry = /* @__PURE__ */ new Map();
 async function acquireWorkspace(key) {
   const existing = workspaceRegistry.get(key);
-  if (existing !== void 0 && existsSync2(existing)) {
+  if (existing !== void 0 && existsSync3(existing)) {
     workspaceRegistry.delete(key);
     workspaceRegistry.set(key, existing);
     return { dir: existing, reused: true };
@@ -1125,7 +1257,7 @@ async function prepareResumingBranch(ctx, dir, reused) {
   return { resumed: true };
 }
 async function sweepWorkspaces() {
-  const base = tmpdir();
+  const base = tmpdir2();
   let entries;
   try {
     entries = await readdir(base);
@@ -1136,7 +1268,7 @@ async function sweepWorkspaces() {
   for (const entry of entries) {
     if (!entry.startsWith(WORKSPACE_PREFIX)) continue;
     try {
-      await rm(join3(base, entry), { recursive: true, force: true });
+      await rm(join4(base, entry), { recursive: true, force: true });
       removed++;
     } catch {
     }
@@ -1370,7 +1502,7 @@ async function prNumbersForCommit(ctx, sha) {
 // src/run.ts
 var IDLE_MS = 5e3;
 var CANCEL_POLL_MS = 2500;
-var ORCHESTRATOR_MODEL = "sonnet";
+var orchestratorModel = (ctx) => rosterFor(ctx.provider).think;
 var ORCHESTRATOR_MAX_TURNS = 80;
 var MAX_COMMIT_REPAIRS = 2;
 var MAX_IMPLEMENT_RETRIES = 1;
@@ -1416,7 +1548,7 @@ async function mergeAndResolveConflicts(ctx, dir, config, abort) {
     cwd: dir,
     prompt: buildResolvePrompt(ctx, related),
     permissionMode: ctx.permissionMode,
-    model: ORCHESTRATOR_MODEL,
+    model: orchestratorModel(ctx),
     maxTurns: ORCHESTRATOR_MAX_TURNS,
     abortController: abort
   });
@@ -1441,7 +1573,7 @@ async function commitWithRepair(ctx, dir, abort) {
         cwd: dir,
         prompt: buildRepairPrompt(ctx, err.log),
         permissionMode: ctx.permissionMode,
-        model: ORCHESTRATOR_MODEL,
+        model: orchestratorModel(ctx),
         maxTurns: ORCHESTRATOR_MAX_TURNS,
         abortController: abort
       });
@@ -1533,13 +1665,19 @@ async function processChatJob(ctx, dir, config, abort) {
   console.log(`
 \u25B6 Job ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
   const orchestrating = ctx.permissionMode !== "plan";
+  const provider = ctx.provider ?? "anthropic";
+  if (provider === "openai" && orchestrating) {
+    throw new Error(
+      "Codex backend currently supports plan mode only. implement/revise/resolve/release jobs with an openai agent are not yet supported."
+    );
+  }
   const installResult = orchestrating ? await installDependencies(dir) : null;
-  const result = await runClaudeCode({
+  const result = provider === "openai" ? await runCodex({ cwd: dir, prompt: buildCodexPrompt(ctx), abortController: abort }) : await runClaudeCode({
     cwd: dir,
     prompt: buildPrompt(ctx),
     permissionMode: ctx.permissionMode,
     abortController: abort,
-    ...orchestrating ? { model: ORCHESTRATOR_MODEL, maxTurns: ORCHESTRATOR_MAX_TURNS } : {}
+    ...orchestrating ? { model: orchestratorModel(ctx), maxTurns: ORCHESTRATOR_MAX_TURNS } : {}
   });
   const summary = result.text.trim();
   let reply = summary || "(the agent produced no summary)";
@@ -1555,7 +1693,7 @@ async function processChatJob(ctx, dir, config, abort) {
     console.log(`  \u2026job ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
     return { text: reply, widgets: result.widgets };
   }
-  const wikiExists = existsSync3(join4(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
   let documented = false;
   if (ctx.permissionMode !== "plan" && wikiExists && await hasChanges(dir)) {
     try {
@@ -1605,7 +1743,7 @@ async function processImplementJob(ctx, dir, resumed, config, abort) {
       cwd: dir,
       prompt: buildPrompt(ctx),
       permissionMode: ctx.permissionMode,
-      model: ORCHESTRATOR_MODEL,
+      model: orchestratorModel(ctx),
       maxTurns: ORCHESTRATOR_MAX_TURNS,
       abortController: abort
     });
@@ -1644,7 +1782,7 @@ ${reply}`;
 
 > \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
   }
-  const wikiExists = existsSync3(join4(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
   let documented = false;
   if (wikiExists && await hasChanges(dir)) {
     try {
@@ -1684,7 +1822,7 @@ async function processReviseJob(ctx, dir, resumed, config, abort) {
     cwd: dir,
     prompt: buildRevisePrompt(ctx),
     permissionMode: ctx.permissionMode,
-    model: ORCHESTRATOR_MODEL,
+    model: orchestratorModel(ctx),
     maxTurns: ORCHESTRATOR_MAX_TURNS,
     abortController: abort
   });
@@ -1700,7 +1838,7 @@ async function processReviseJob(ctx, dir, resumed, config, abort) {
     console.log(`  \u2026revise ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
     return { text: reply, widgets: result.widgets };
   }
-  const wikiExists = existsSync3(join4(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
   let documented = false;
   if (wikiExists && await hasChanges(dir)) {
     try {
@@ -1774,7 +1912,7 @@ async function processReleaseJob(ctx, dir, resumed, config, abort) {
     cwd: dir,
     prompt: buildReleasePrompt(ctx, baseChecks),
     permissionMode: ctx.permissionMode,
-    model: ORCHESTRATOR_MODEL,
+    model: orchestratorModel(ctx),
     maxTurns: ORCHESTRATOR_MAX_TURNS,
     abortController: abort
   });

package/dist/mcp-stdio.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/mcp-stdio.ts
+import { appendFileSync, writeFileSync, existsSync } from "node:fs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { toJSONSchema } from "zod/v4/core";
+import { z as z3 } from "zod";
+
+// src/plan.ts
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+
+// src/code-lang.ts
+var EXT_TO_LANG = {
+  ts: "typescript",
+  tsx: "tsx",
+  js: "javascript",
+  jsx: "jsx",
+  json: "json",
+  css: "css",
+  md: "markdown",
+  sh: "bash",
+  py: "python",
+  yaml: "yaml",
+  yml: "yaml",
+  html: "markup",
+  xml: "markup",
+  sql: "sql"
+};
+function langFromPath(path) {
+  const ext = path.split(".").pop()?.toLowerCase();
+  return ext ? EXT_TO_LANG[ext] : void 0;
+}
+
+// src/schema-hints.ts
+var INLINE_CODE_HINT = "Wrap code identifiers (function, variable, type, and file names, commands, and flags) in inline backticks, e.g. `getCodingSessionsForRequest`.";
+var WIDGET_LANGUAGE_HINT = "Write this in the same natural language as the incoming thread (the request body and the user's messages). If the thread is in English, keep it in English; do not switch languages. Keep code identifiers, file paths, and quoted code verbatim.";
+
+// src/plan.ts
+var SERVER_NAME = "flume_plan";
+var SUBMIT_PLAN = "submit_plan";
+var PLAN_TOOL_NAME = `mcp__${SERVER_NAME}__${SUBMIT_PLAN}`;
+var PLAN_MARKER = "<!-- flumecode:end-of-plan -->";
+var pseudoCodeEntrySchema = z.object({
+  file: z.string().min(1),
+  pseudoCode: z.string().min(1)
+});
+var stepSchema = z.object({
+  title: z.string().min(1).describe("A concise imperative title for this step."),
+  description: z.array(z.string().min(1)).min(1).describe(
+    "Bullet points that explain this step's change so a reviewer can judge whether the design is correct. Each array item is one short, self-contained bullet \u2014 not a single paragraph, and not a restatement of the pseudo code. " + INLINE_CODE_HINT
+  ),
+  pseudoCode: z.array(pseudoCodeEntrySchema).optional().describe(
+    "Per-file pseudo code. Provide an entry for every non-documentation file this step touches. Each entry contains the file path and pseudo code describing the changes to that file."
+  )
+});
+var planInputSchema = {
+  title: z.string().min(1).max(120).describe(
+    "A concise, descriptive name for THIS plan. Must be distinct from the request title and from any sibling plans on the same request. Keep it under 120 characters."
+  ),
+  scope: z.enum(["feat", "fix", "chore", "docs", "test", "refactor"]).describe("The primary intent of the change."),
+  goal: z.string().min(1).describe("One or two sentences stating the outcome. " + INLINE_CODE_HINT),
+  rootCause: z.string().optional().describe(
+    'For bug fixes (scope === "fix"): the underlying cause of the bug \u2014 the specific code, logic, or condition that produces the incorrect behavior, not just the symptom. Required when scope is "fix"; omit for all other scopes. ' + INLINE_CODE_HINT
+  ),
+  motivation: z.string().optional().describe(
+    "Why the user is making this request \u2014 the underlying motivation or problem the change addresses. Fill this especially when the request content/context does NOT already state the why (ask the user in the Clarify phase); omit when there is no additional motivation to record. Useful for future understanding of the system. " + INLINE_CODE_HINT
+  ),
+  assumptions: z.array(z.string()).describe("Anything decided during planning, including unanswered defaults."),
+  requirements: z.array(z.string().min(1)).min(1).describe(
+    "Required, human-readable statements of what this change must accomplish and why, in plain language a non-technical reader can follow. Distinct from acceptanceCriteria: requirements explain intent/rationale; acceptance criteria are the machine-checkable proof. At least 1 required. " + INLINE_CODE_HINT
+  ),
+  steps: z.array(stepSchema).min(1).describe("Ordered list of changes. Each step says what and why, with file references."),
+  acceptanceCriteria: z.array(z.string().min(1)).min(2).describe(
+    "Concrete, deterministically-checkable conditions that together define done. Each names a trigger/precondition and the exact observable result (run X -> output Y; file Z contains W; f(a) returns b) \u2014 no vague adjectives, not a restatement of a step. The set must collectively cover every step's change. At least 2 required. " + INLINE_CODE_HINT
+  ),
+  risks: z.array(z.string()).describe("Anything that could change the approach."),
+  outOfScope: z.array(z.string()).describe("What is deliberately not being done.")
+};
+function requireRootCauseForFix(schema) {
+  return schema.superRefine((plan, ctx) => {
+    if (plan.scope === "fix" && (plan.rootCause === void 0 || plan.rootCause.trim() === "")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["rootCause"],
+        message: 'rootCause is required and must be non-empty when scope is "fix".'
+      });
+    }
+  });
+}
+var planSchema = requireRootCauseForFix(z.object(planInputSchema));
+function renderPlan(plan) {
+  const lines = [];
+  lines.push(`# ${plan.title}`);
+  lines.push("");
+  lines.push(`**Scope** \u2014 \`${plan.scope}\``);
+  lines.push("");
+  lines.push(`**Goal** \u2014 ${plan.goal}`);
+  if (plan.motivation && plan.motivation.trim().length > 0) {
+    lines.push("");
+    lines.push("## Motivation");
+    lines.push(plan.motivation);
+  }
+  if (plan.assumptions.length > 0) {
+    lines.push("");
+    lines.push("**Assumptions**");
+    for (const assumption of plan.assumptions) {
+      lines.push(`- ${assumption}`);
+    }
+  }
+  if (plan.rootCause && plan.rootCause.trim().length > 0) {
+    lines.push("");
+    lines.push("## Root cause");
+    lines.push(plan.rootCause);
+  }
+  lines.push("");
+  lines.push("## Requirements");
+  for (const requirement of plan.requirements) {
+    lines.push(`- ${requirement}`);
+  }
+  lines.push("");
+  lines.push("## Steps");
+  for (const [i, step] of plan.steps.entries()) {
+    lines.push("");
+    lines.push(`### ${i + 1}. ${step.title}`);
+    lines.push("");
+    for (const bullet of step.description) {
+      lines.push(`- ${bullet}`);
+    }
+    if (step.pseudoCode && step.pseudoCode.length > 0) {
+      for (const entry of step.pseudoCode) {
+        lines.push("");
+        lines.push(`\`${entry.file}\``);
+        lines.push("");
+        const lang = langFromPath(entry.file);
+        lines.push(lang ? "```" + lang : "```");
+        lines.push(entry.pseudoCode);
+        lines.push("```");
+      }
+    }
+  }
+  lines.push("");
+  lines.push("## Acceptance criteria");
+  for (const criterion of plan.acceptanceCriteria) {
+    lines.push(`- [ ] ${criterion}`);
+  }
+  if (plan.risks.length > 0) {
+    lines.push("");
+    lines.push("**Risks / open questions**");
+    for (const risk of plan.risks) {
+      lines.push(`- ${risk}`);
+    }
+  }
+  if (plan.outOfScope.length > 0) {
+    lines.push("");
+    lines.push("**Out of scope**");
+    for (const item of plan.outOfScope) {
+      lines.push(`- ${item}`);
+    }
+  }
+  lines.push("");
+  lines.push(PLAN_MARKER);
+  return lines.join("\n");
+}
+var submitPlanInputSchema = {
+  plans: z.array(requireRootCauseForFix(z.object(planInputSchema))).min(1).refine(
+    (arr) => {
+      const titles = arr.map((p) => p.title.trim()).filter((t) => t.length > 0);
+      return new Set(titles).size === titles.length;
+    },
+    { message: "Each plan must have a distinct non-empty title" }
+  )
+};
+var submitPlanSchema = z.object(submitPlanInputSchema);
+
+// src/widgets.ts
+import { randomUUID } from "node:crypto";
+import { createSdkMcpServer as createSdkMcpServer2, tool as tool2 } from "@anthropic-ai/claude-agent-sdk";
+import { z as z2 } from "zod";
+var SERVER_NAME2 = "flume_widgets";
+var SINGLE_SELECT = "single_select";
+var MULTI_SELECT = "multi_select";
+var WIDGET_TOOL_NAMES = [
+  `mcp__${SERVER_NAME2}__${SINGLE_SELECT}`,
+  `mcp__${SERVER_NAME2}__${MULTI_SELECT}`
+];
+var optionsSchema = z2.array(z2.string().min(1)).min(2).max(8).describe("2\u20138 short, distinct choices for the user to pick from. " + WIDGET_LANGUAGE_HINT);
+var TAIL = "Do NOT add an 'Other' or 'None of these' catch-all \u2014 the UI always offers an 'Other' free-text option automatically. " + WIDGET_LANGUAGE_HINT + " After calling this, END YOUR TURN and wait: the user's answer arrives as their next message and starts a fresh run.";
+var singleSelectShape = {
+  question: z2.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
+  body: z2.string().optional().describe(
+    "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
+  ),
+  options: optionsSchema
+};
+var multiSelectShape = {
+  question: z2.string().min(1).describe("The question to ask the user. " + WIDGET_LANGUAGE_HINT),
+  body: z2.string().optional().describe(
+    "Optional markdown shown above the question so the user can read the context they're confirming (e.g. the drafted release notes). Omit for plain questions."
+  ),
+  options: optionsSchema
+};
+function buildSingleSelectWidget(args) {
+  return {
+    id: randomUUID(),
+    type: "single_select",
+    question: args.question,
+    body: args.body,
+    options: args.options.map((label) => ({ id: randomUUID(), label })),
+    selectedOptionId: null,
+    customAnswer: null
+  };
+}
+function buildMultiSelectWidget(args) {
+  return {
+    id: randomUUID(),
+    type: "multi_select",
+    question: args.question,
+    body: args.body,
+    options: args.options.map((label) => ({ id: randomUUID(), label })),
+    selectedOptionIds: null,
+    customAnswer: null
+  };
+}
+
+// src/mcp-stdio.ts
+var OUT = process.env.FLUME_MCP_OUTPUT;
+if (!OUT) {
+  console.error("FLUME_MCP_OUTPUT env var not set");
+  process.exit(1);
+}
+if (!existsSync(OUT)) {
+  writeFileSync(OUT, "");
+}
+function emit(rec) {
+  appendFileSync(OUT, JSON.stringify(rec) + "\n");
+}
+function ack(text) {
+  return { content: [{ type: "text", text }] };
+}
+function shapeToJsonSchema(shape) {
+  return toJSONSchema(z3.object(shape));
+}
+var TOOLS = [
+  {
+    name: "submit_plan",
+    description: "Submit ALL your plans in a single call \u2014 one entry per plan; each becomes its own independently-acceptable plan draft. Do NOT call submit_plan more than once.",
+    inputSchema: toJSONSchema(submitPlanSchema)
+  },
+  {
+    name: "single_select",
+    description: "Ask the user a single-select (radio-button) question \u2014 exactly one answer.",
+    inputSchema: shapeToJsonSchema(singleSelectShape)
+  },
+  {
+    name: "multi_select",
+    description: "Ask the user a multi-select (checkbox) question \u2014 they may pick any number of options.",
+    inputSchema: shapeToJsonSchema(multiSelectShape)
+  }
+];
+var server = new Server({ name: "flume", version: "1" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  if (name === "submit_plan") {
+    const parsed = submitPlanSchema.parse(args);
+    emit({ kind: "plans", plans: parsed.plans.map(renderPlan) });
+    return ack("Plan(s) submitted. End your turn.");
+  }
+  if (name === "single_select") {
+    const parsed = z3.object(singleSelectShape).parse(args);
+    emit({ kind: "widget", widget: buildSingleSelectWidget(parsed) });
+    return ack("Question posted as a single-select widget. End your turn.");
+  }
+  if (name === "multi_select") {
+    const parsed = z3.object(multiSelectShape).parse(args);
+    emit({ kind: "widget", widget: buildMultiSelectWidget(parsed) });
+    return ack("Question posted as a multi-select widget. End your turn.");
+  }
+  throw new Error(`Unknown tool: ${name}`);
+});
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumecode/runner",
-  "version": "0.19.0",
+  "version": "0.21.0-beta.1",
   "type": "module",
   "description": "FlumeCode local runner — claims jobs and drives your local Claude Code against a real checkout.",
   "bin": {
@@ -18,7 +18,7 @@
     "provenance": false
   },
   "scripts": {
-    "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --packages=external --outfile=dist/cli.js --banner:js=\"#!/usr/bin/env node\"",
+    "build": "esbuild src/cli.ts src/mcp-stdio.ts --bundle --platform=node --format=esm --target=node20 --packages=external --outdir=dist --banner:js=\"#!/usr/bin/env node\"",
     "dev": "tsx src/cli.ts",
     "login": "tsx src/cli.ts login",
     "start": "tsx src/cli.ts start",
@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",
+    "@modelcontextprotocol/sdk": "^1",
     "zod": "4.4.3"
   },
   "devDependencies": {

package/skills-plugin/skills/implement-plan/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 
 # implement-plan
 
-You are the **orchestrator**. You run on a medium model and your job is to
+You are the **orchestrator**. You run on the `think` model and your job is to
 _coordinate_, not to write the implementation. You delegate each phase to a
 subagent through the **Task** tool, choosing the model that phase needs, and you
 stitch their results into one report. Doing the implementation yourself defeats
@@ -30,10 +30,9 @@ put it in the prompt, the subagent doesn't have it.
 ## How you delegate
 
 - Spawn each phase with the **Task** tool, `subagent_type: "general-purpose"`.
-- **Model per phase** (pass it as the Task `model` argument):
-  - `"sonnet"` — implementation, fixes, and the Verify step (mechanical
-    command-running; Verify is read-only even though it uses sonnet).
-  - `"opus"` — acceptance-criteria review, code-quality review, and the report.
+- **Model per phase** (pass the concrete id from the Model tiers block as the Task `model` argument):
+  - `execute` — implementation, fixes, and the Verify step (mechanical command-running; Verify is read-only).
+  - `think` — acceptance-criteria review, code-quality review, and the report.
 - **Read-only phases.** Tell every review, Verify, and report subagent to _inspect
   and report only — never edit, create, or delete files_. Only implementation/fix
   subagents may change the working tree.
@@ -68,7 +67,7 @@ the next step.
    it in the prompts you write for the Implement, Verify, and Fix-loop subagents
    so none of them re-derive it. Do not implement.
 
-2. **Implement** — Task, `model: "sonnet"`. Give the subagent: the plan steps, a
+2. **Implement** — Task, `model: execute`. Give the subagent: the plan steps, a
    pointer to the wiki/orientation, the coding guidelines (verbatim), and the
    explicit verification command list the orchestrator discovered in the Orient
    step. Tell it to make all the code changes in the working tree to satisfy the
@@ -83,7 +82,7 @@ the next step.
    the verification commands it ran and their pass/fail results, which files it
    changed, and how each plan step was addressed. It must not commit or push.
 
-3. **Verify (build & tests)** — Task, `model: "sonnet"`, read-only. This step
+3. **Verify (build & tests)** — Task, `model: execute`, read-only. This step
    gives the orchestrator an objective, independent build/test signal before the
    subjective AC and quality reviews. Tell the subagent to:
    - Run the verification commands provided by the orchestrator in the task
@@ -100,7 +99,7 @@ the next step.
      excerpt (if any).
    - Must not edit, create, or delete any files.
 
-4. **Acceptance-criteria review** — Task, `model: "opus"`, read-only. Give the
+4. **Acceptance-criteria review** — Task, `model: think`, read-only. Give the
    subagent the full AC list and tell it to verify each one against the actual
    changes (run `git --no-pager diff`, read the changed files, run tests/build if
    useful). For **each** AC it must return: the criterion text verbatim, a verdict
@@ -117,7 +116,7 @@ the next step.
    note any files or areas that appear changed but don't map to any AC as a coverage
    gap (signalling a missing AC or an out-of-scope change).
 
-5. **Code-quality review** — Task, `model: "opus"`, read-only. Give the subagent
+5. **Code-quality review** — Task, `model: think`, read-only. Give the subagent
    the coding guidelines (verbatim) and tell it to review the changes for
    violations and quality problems, returning concrete findings as
    `file:line — what — why`, each marked **must-fix** or **nice-to-have**.
@@ -125,7 +124,7 @@ the next step.
 6. **Fix loop.** If the Verify step (step 3) reports any failing check, the AC
    review (step 4) reports any _not met_ AC, or the quality review (step 5)
    reports any _must-fix_ finding: spawn an **Implement/fix** subagent (Task,
-   `model: "sonnet"`) whose prompt lists exactly those findings and tells it to
+   `model: execute`) whose prompt lists exactly those findings and tells it to
    resolve them without regressing the rest. Include the verification command list
    from the Orient step in the fix subagent's prompt (the same list passed to
    Implement and Verify), so the fix subagent does not need to re-derive it. When
@@ -135,7 +134,7 @@ the next step.
    times. If something still fails after that, stop looping and record the gap
    honestly in the report — do not hide it.
 
-7. **Report** — Task, `model: "opus"`, read-only. Give the subagent the AC
+7. **Report** — Task, `model: think`, read-only. Give the subagent the AC
    verdicts (with criterion text, from step 4), the Verify results (from step 3),
    and the quality findings, and tell it to run `git --no-pager diff` itself as
    the **single source of truth** for the report. Pass the Verify results as the
@@ -191,7 +190,7 @@ The report subagent calls `submit_report` with these fields:
 
 - Delegate through Task subagents; don't implement, review, or write the report
   yourself.
-- Right model per phase: `sonnet` to implement/fix/verify (Verify is read-only), `opus` to review/report.
+- Right model per phase: `execute` to implement/fix/verify (Verify is read-only), `think` to review/report.
 - Make every Task prompt self-contained — subagents see only what you give them.
 - Reviewers and the report writer never modify files.
 - Never commit, push, or open a PR.

package/skills-plugin/skills/request-to-plan/SKILL.md

@@ -34,7 +34,10 @@ and determine which phase you are in:**
    If the request is a bug fix, investigate deeply enough to identify the **root cause** (the specific code or condition producing the incorrect behavior) before proceeding to Plan — you will need it for the `rootCause` field.
 2. Identify genuine ambiguity only: scope, intended behavior, edge cases,
    competing approaches, acceptance criteria. Skip anything you can reasonably
-   decide yourself.
+   decide yourself. One high-leverage question is the user's motivation — **why** they
+   are making this request — but only when the request title/body and context don't
+   already explain it. Never re-ask what the thread already answers (consistent with
+   "Never ask what the code answers").
 3. End your turn with **2–5 specific, high-leverage questions**, each with a
    recommended default so the user can reply "all defaults" if they want. Group
    them; keep it short. Do **not** include a plan yet.
@@ -66,6 +69,7 @@ Field-by-field guidance:
   answers the request's title and body. Must be achievable by the steps below
   and nothing more.
 - **`rootCause`** — required when `scope` is `fix`; omit for all other scopes. Identify the underlying cause of the bug — the specific code, logic, or condition that produces the incorrect behavior, **not** the symptom. To fill this accurately, you must investigate the codebase deeply enough to find the root cause before writing the plan.
+- **`motivation`** — optional. The user's stated or asked-for reason for making this request — the underlying motivation or problem the change addresses. Fill this when the request content/context does NOT already state the why (ask during Phase 1 — Clarify if needed); omit when there is no additional motivation to record. Useful for future understanding of the system.
 - **`assumptions`** — anything you decided during investigation (including
   unanswered defaults from Phase 1).
 - **`requirements`** — **required; at least 1 item.** Plain-language statements of what this change must accomplish and why, written so a non-technical reader can follow them. Distinct from `acceptanceCriteria`: requirements explain intent and rationale; acceptance criteria are the machine-checkable proof. At least 1 item required.

package/skills-plugin/skills/revise-implementation/SKILL.md

@@ -67,9 +67,9 @@ essentials:
   implementation, not a rebuild. Change only what the user asked for plus what that
   change strictly requires; don't regress the rest of the plan.
 - **Pipeline:** Implement (self-runs build/tests & fixes its own errors, Task
-  `model: "sonnet"`) → Verify (build/tests, read-only, Task `model: "sonnet"`) →
-  acceptance/quality review (Task `model: "opus"`, read-only) → fix loop if needed
-  (≤2, re-run Verify after each fix) → report (Task `model: "opus"`, read-only).
+  `model: execute`) → Verify (build/tests, read-only, Task `model: execute`) →
+  acceptance/quality review (Task `model: think`, read-only) → fix loop if needed
+  (≤2, re-run Verify after each fix) → report (Task `model: think`, read-only).
   Detailed mechanics (command discovery, Verify step spec, fix-loop trigger
   conditions) are in `implement-plan/SKILL.md` — read it for the full pipeline.
 - **No git side effects.** Never commit, push, or open a PR — leave the changes in