kaizen-agent 1.5.5 → 1.6.0

package/README.md

@@ -543,6 +543,9 @@ in one can be finished in another. See [adapters.md](https://github.com/hfadhlul
 | `auto_fix.min_severity` | `high` | Findings this bad or worse get fixed without asking |
 | `approvals.plan` | `true` | Stop and show the plan before anything is built |
 | `ui.mouse` | `false` | Click to select, click again to act; while on, the terminal cannot select text |
+| `subagents.model` | `inherit` | Model the stage subagents run on: `inherit`, `opus`, `sonnet`, `haiku` (Claude Code only) |
+| `agent.<cmd>.model`, `agent.<cmd>.effort` | — | Model/effort the board launches a session with, per tool: `claude`, `codex`, `agy`, `opencode`, `gemini`. Model names are the tool's own (`agy models`) |
+| `subagents.effort` | `inherit` | Reasoning effort for the stage subagents: `inherit`, `low`, `medium`, `high` (Claude Code only) |
 
 ```bash
 kaizen settings

package/cli/settings.ts

@@ -4,7 +4,7 @@ import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } from
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 
-type Setting = { key: string; values: string[]; help: string };
+type Setting = { key: string; label: string; group: string; values: string[]; help: string };
 
 export type PresetName = "low" | "medium" | "ultra";
 
@@ -93,24 +93,26 @@ export function applyPreset(text: string, preset: PresetName, defaults: string):
 }
 
 const SETTINGS: Setting[] = [
-  { key: "preset", values: ["low", "medium", "ultra", "custom"], help: "Quick preset — low: inline & manual, medium: balanced, ultra: autonomous subagents" },
-  { key: "mode", values: ["approve", "auto", "plan-only", "review-only"], help: "Where a run stops" },
-  { key: "runner", values: ["full", "lite"], help: "full: every stage its own cold agent. lite: this session runs them all, cheaper, reviewer has seen the work" },
-  { key: "build.executor", values: ["subagent", "inline", "ask"], help: "Who carries out the approved plan" },
-  { key: "approvals.plan", values: ["true", "false"], help: "Stop and show the plan before anything is built" },
-  { key: "approvals.review", values: ["true", "false"], help: "Stop after the review, before the run is done" },
-  { key: "approvals.each_file", values: ["true", "false"], help: "Confirm every individual edit" },
-  { key: "auto_fix.enabled", values: ["true", "false"], help: "Fix findings without asking" },
-  { key: "auto_fix.min_severity", values: ["critical", "high", "medium", "low"], help: "How bad a finding must be to be fixed automatically" },
-  { key: "auto_fix.max_iterations", values: ["1", "2", "3", "4", "5"], help: "Fix and recheck rounds before escalating" },
-  { key: "review.write_memory", values: ["true", "false"], help: "Let the reviewer append lessons to memory.md" },
-  { key: "review.memory_max_lines", values: ["50", "100", "200", "400"], help: "Size cap on memory.md, a tax on every run" },
-  { key: "track.default", values: ["", "software", "writing", "communication", "operations", "research"], help: "Pin a track, or leave empty to infer per run" },
-  { key: "state.keep_runs", values: ["5", "10", "20", "50"], help: "Completed runs kept before the oldest is pruned" },
-  { key: "git.auto_commit", values: ["false", "true"], help: "Commit the work when a run finishes" },
-  { key: "git.branch_before_implement", values: ["true", "false"], help: "Branch before building when on the default branch" },
-  { key: "ui.mouse", values: ["false", "true"], help: "Click to select, click again to act. While on, the terminal cannot select text with the mouse" },
-  { key: "agent.default", values: ["auto", "claude", "codex", "agy", "opencode", "gemini"], help: "Default coding agent to launch from dashboard backlog" },
+  { key: "preset", label: "Preset", group: "Preset", values: ["low", "medium", "ultra", "custom"], help: "Sets every row below at once. low: you do it here, step by step. medium: balanced. ultra: hands-off. Change any row and it becomes custom" },
+  { key: "mode", label: "Stop for approval", group: "Run", values: ["approve", "auto", "plan-only", "review-only"], help: "approve: pause and ask you at each enabled checkpoint. auto: never pause. plan-only: write the plan and stop. review-only: just audit existing work" },
+  { key: "git.auto_commit", label: "Commit when done", group: "Run", values: ["false", "true"], help: "Commit the work when a run finishes. Never pushes" },
+  { key: "state.keep_runs", label: "Runs to keep", group: "Run", values: ["5", "10", "20", "50"], help: "Finished runs kept before the oldest is pruned. Open backlog items are rescued first" },
+  { key: "ui.mouse", label: "Enable mouse", group: "Run", values: ["false", "true"], help: "Click to select, click again to act. While on, the terminal cannot select text with the mouse" },
+  { key: "approvals.plan", label: "Approve the plan first", group: "Planning", values: ["true", "false"], help: "Show the plan and wait for your OK before anything is built" },
+  { key: "track.default", label: "Kind of work", group: "Planning", values: ["auto", "software", "writing", "communication", "operations", "research"], help: "Pin what runs in this project are (a docs repo is always writing). auto: the planner infers it per run" },
+  { key: "build.executor", label: "Who builds", group: "Building", values: ["subagent", "inline", "ask"], help: "subagent: a separate agent builds and reports back. inline: this session builds while you watch. ask: choose at the plan approval" },
+  { key: "approvals.each_file", label: "Confirm every file edit", group: "Building", values: ["true", "false"], help: "Ask before each individual file change. Maximum control, slowest" },
+  { key: "git.branch_before_implement", label: "Branch before building", group: "Building", values: ["true", "false"], help: "Create a branch before building when you are on the default branch" },
+  { key: "approvals.review", label: "Approve after review", group: "Review", values: ["true", "false"], help: "After the review, wait for your OK before the run is called done" },
+  { key: "auto_fix.enabled", label: "Fix findings automatically", group: "Review", values: ["true", "false"], help: "true: findings severe enough get fixed and re-reviewed without asking. false: every finding stops and asks you" },
+  { key: "auto_fix.min_severity", label: "Auto-fix from severity", group: "Review", values: ["critical", "high", "medium", "low"], help: "The least severe finding still fixed automatically. low fixes everything; critical fixes almost nothing" },
+  { key: "auto_fix.max_iterations", label: "Max fix rounds", group: "Review", values: ["1", "2", "3", "4", "5"], help: "Fix-then-recheck rounds before leftovers are handed to you. Each round is a full build plus a full review, the priciest knob here" },
+  { key: "review.write_memory", label: "Remember lessons", group: "Review", values: ["true", "false"], help: "Let the reviewer save what it learned to .kaizen/memory.md, which every future run reads" },
+  { key: "review.memory_max_lines", label: "Memory size cap", group: "Review", values: ["50", "100", "200", "400"], help: "Lines memory.md may hold before old lessons are pruned. Every run reads it, so bigger costs more" },
+  { key: "runner", label: "Stage isolation", group: "Agents", values: ["full", "lite"], help: "full: each stage is a fresh agent, so the reviewer never saw the work (costs more). lite: this one session does every stage, cheaper, reviewer may miss its own mistakes" },
+  { key: "subagents.model", label: "Model for stage agents", group: "Agents", values: ["inherit", "opus", "sonnet", "haiku"], help: "Which Claude model the planner, builder and reviewer run on. inherit: same as your main session. Claude Code only" },
+  { key: "subagents.effort", label: "Effort for stage agents", group: "Agents", values: ["inherit", "low", "medium", "high"], help: "How hard the stage agents think. low is faster and cheaper; high finds more. Claude Code only" },
+  { key: "agent.default", label: "Tool the board launches", group: "Agents", values: ["auto", "claude", "codex", "agy", "opencode", "gemini"], help: "Coding tool opened when you start a run from the board. auto: Claude Code if installed, else the first one found" },
 ];
 
 // The same rows and the same write the TUI uses, for `kaizen web`'s settings panel:
@@ -124,7 +126,7 @@ export function listSettings(repoRoot: string) {
     file: tilde(file),
     rows: SETTINGS.map((s) => ({
       ...s,
-      value: s.key === "preset" ? preset : read(text, s.key) ?? read(defaults, s.key) ?? s.values[0]!,
+      value: s.key === "preset" ? preset : (read(text, s.key) || read(defaults, s.key)) ?? s.values[0]!,
     })),
   };
 }
@@ -176,26 +178,48 @@ export async function settings(repoRoot: string, standalone = true) {
 
   const defaults = readFileSync(join(repoRoot, "skills/kaizen/config.default.yml"), "utf8");
   let active = 0, saved = "";
+  // Screen line -> setting index, rebuilt on every draw; the mouse clicks by line.
+  let rowAt: number[] = [];
   const draw = () => {
     const text = readFileSync(file, "utf8");
     const currentPreset = detectPreset(text, defaults);
+    // Booleans as a checkbox, numeric scales as a level bar; the file still holds the words.
+    const show = (s: Setting, v: string) => {
+      if (s.values.length === 2 && s.values.includes("true")) return v === "true" ? "[✓] on" : "[ ] off";
+      if (s.values.every((x) => /^\d+$/.test(x))) {
+        const at = s.values.indexOf(v);
+        return at < 0 ? v : "▮".repeat(at + 1) + "▯".repeat(s.values.length - at - 1) + " " + v;
+      }
+      return v;
+    };
     const rows = SETTINGS.map((s) => ({
       s,
-      value: s.key === "preset" ? currentPreset : (read(text, s.key) ?? c.dim("(default)")),
+      // Older configs spell "infer the track" as an empty string; show what it means.
+      value: s.key === "preset" ? currentPreset : show(s, (read(text, s.key) || (s.key === "track.default" ? "auto" : undefined)) ?? c.dim("(default)")),
     }));
-    const width = Math.max(...SETTINGS.map((s) => s.key.length)) + 4;
+    const width = Math.max(...SETTINGS.map((s) => s.label.length)) + 4;
 
     stdout.write("\x1b[H\x1b[2J");           // home, clear
-    stdout.write(`\n  ${c.bold("kaizen settings")}   ${c.dim(tilde(file))}\n\n`);
+    stdout.write(`\n  ${c.bold("kaizen settings")}   ${c.dim(tilde(file))}\n`);
+    rowAt = [];
+    let line = 2, group = "";
     for (const [i, { s, value }] of rows.entries()) {
+      if (s.group !== group) {
+        group = s.group;
+        stdout.write(`\n  ${c.dim(group.toUpperCase())}\n`);
+        line += 2;
+      }
       const on = i === active;
-      const name = s.key.padEnd(width);
+      const name = s.label.padEnd(width);
       stdout.write(on
         ? `  ${c.cyan("›")} ${c.bold(name)}${c.inv(` ${value} `)}\n`
         : `    ${c.dim(name)}${value}\n`);
+      rowAt[line++] = i;
     }
-    stdout.write(`\n  ${c.dim(SETTINGS[active]!.help)}\n`);
-    stdout.write(`\n  ${c.dim("↑↓ move · ←→ change · backspace back")}   ${saved}\n`);
+    const cur = SETTINGS[active]!;
+    stdout.write(`\n  ${c.dim(cur.key)}  ${c.dim("options:")} ${cur.values.map((v) => v || '""').join(c.dim(" / "))}\n`);
+    stdout.write(`  ${cur.help}\n`);
+    stdout.write(`\n  ${c.dim("↑↓ pick a setting · ←→ or enter to change it (saved instantly) · esc back")}   ${saved}\n`);
   };
 
   stdout.write("\x1b[?1049h\x1b[?25l");      // alternate screen, hide cursor
@@ -245,7 +269,6 @@ export async function settings(repoRoot: string, standalone = true) {
       const keys = chunk.toString();
       for (let i = 0; i < keys.length; i++) {
         const rest = keys.slice(i);
-        // Rows begin on the fourth line: blank, title, blank, then the settings.
         const m = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])/.exec(rest);
         if (m) {
           i += m[0].length - 1;
@@ -253,8 +276,8 @@ export async function settings(repoRoot: string, standalone = true) {
           if (button === 64) active = (active - 1 + SETTINGS.length) % SETTINGS.length;
           else if (button === 65) active = (active + 1) % SETTINGS.length;
           else if (press && button === 0) {
-            const row = y - 4;
-            if (row < 0 || row >= SETTINGS.length) continue;
+            const row = rowAt[y - 1];
+            if (row === undefined) continue;
             // Click to select; click the selected row to cycle it, which is what
             // the right arrow already does.
             if (row === active) { cycle(1); continue; }

package/cli/state.test.ts

@@ -7,7 +7,7 @@ import { tmpdir } from "node:os";
 import {
   readRuns, readInbox, writeInbox, replaceIdea, abandonRun, allBacklog, backlog,
   statusOf, columnOf, parseItem, startedRuns, boardCards, readArchive, setArchived,
-  requestOf, readNotes, writeNotes, manualCommand, parseNotes, formatNote, appendNote, saveAttachment,
+  requestOf, agentFlags, readNotes, writeNotes, manualCommand, parseNotes, formatNote, appendNote, saveAttachment,
 } from "./state.ts";
 
 let state: string;
@@ -57,7 +57,11 @@ test("statusOf: waiting beats stage, mtime decides running vs stalled", () => {
 });
 
 test("columnOf: every stage word lands somewhere", () => {
-  expect(["plan", "build", "review", "done", "abandoned", "weird"].map(columnOf)).toEqual([1, 2, 3, 4, 4, 1]);
+  expect(["plan", "build", "review", "done", "abandoned", "weird"].map((s) => columnOf(s))).toEqual([1, 2, 3, 4, 4, 1]);
+  expect(columnOf("implement", "approvals.review")).toBe(3);
+  expect(columnOf("implement", "findings")).toBe(3);
+  expect(columnOf("implement", "approvals.each_file")).toBe(2);
+  expect(columnOf("plan", "approvals.plan")).toBe(1);
 });
 
 test("inbox round-trips and ignores malformed lines", () => {
@@ -182,3 +186,12 @@ test("notes log: append to a run and to an idea; attachments saved and made abso
   expect(requestOf("x", `![s](${rel})`, state)).toBe(`x\n\n![s](${join(state, rel)})`);
   expect(saveAttachment(state, "2026-09-01-waiting", "b.txt", new Uint8Array([2]))).toMatch(/^runs\/2026-09-01-waiting\/attachments\//);
 });
+
+test("agentFlags: per-tool model and effort from the agent block, inline or nested", () => {
+  const cfg = `agent:\n  default: auto\n  codex: { model: gpt-5, effort: low }\n  claude:\n    model: sonnet\n    effort: low\n  gemini:\n    model: "gemini-2.5-pro"\n`;
+  expect(agentFlags("/p", "codex", cfg)).toEqual(["-m", "gpt-5", "-c", "model_reasoning_effort=low"]);
+  expect(agentFlags("/p", "claude", cfg)).toEqual(["--model", "sonnet", "--effort", "low"]);
+  expect(agentFlags("/p", "gemini", cfg)).toEqual(["-m", "gemini-2.5-pro"]);
+  expect(agentFlags("/p", "agy", cfg)).toEqual([]);
+  expect(agentFlags("/p", "codex", "agent:\n  default: codex\n")).toEqual([]);
+});

package/cli/state.ts

@@ -41,6 +41,35 @@ export function detectDefaultAgent(projectDir: string): { name: string; cmd: str
   return { name: "Claude Code", cmd: "claude" };
 }
 
+// Flags that pin the launched session's model and effort, from the config chain:
+//   agent:
+//     codex: { model: gpt-5, effort: low }
+// Each tool spells the flag its own way; a tool not listed here takes none.
+const MODEL_FLAGS: Record<string, (m: string) => string[]> = {
+  claude: (m) => ["--model", m], agy: (m) => ["--model", m], codex: (m) => ["-m", m],
+  gemini: (m) => ["-m", m], opencode: (m) => ["-m", m],
+};
+const EFFORT_FLAGS: Record<string, (e: string) => string[]> = {
+  claude: (e) => ["--effort", e], agy: (e) => ["--effort", e],
+  codex: (e) => ["-c", `model_reasoning_effort=${e}`],
+};
+
+export function agentFlags(projectDir: string, cmd: string, configText?: string): string[] {
+  if (configText === undefined) {
+    const f = [join(projectDir, ".kaizen", "config.yml"), join(home, ".kaizen", "config.yml")].find(existsSync);
+    configText = f ? readFileSync(f, "utf8") : "";
+  }
+  // ponytail: regex over the yaml, like detectDefaultAgent; a parser when a third key needs it
+  const block = new RegExp(`^agent:\\n(?:[ \\t]+.*\\n)*?[ \\t]+${cmd}:[ \\t]*(\\{[^}]*\\}|\\n(?:[ \\t]+[a-z]+:.*\\n?)+)`, "m").exec(configText);
+  if (!block) return [];
+  const get = (k: string) => new RegExp(`\\b${k}:[ \\t]*["']?([^"',}\\s]+)`).exec(block[1])?.[1];
+  const model = get("model"), effort = get("effort");
+  return [
+    ...(model && MODEL_FLAGS[cmd] ? MODEL_FLAGS[cmd](model) : []),
+    ...(effort && EFFORT_FLAGS[cmd] ? EFFORT_FLAGS[cmd](effort) : []),
+  ];
+}
+
 export function findTerminal(cwd: string, fullCmd: string[]): { cmd: string[]; detached: boolean } | null {
   const hasDisplay = Boolean(process.env.WAYLAND_DISPLAY || process.env.DISPLAY);
   const inTmux = Boolean(process.env.TMUX);
@@ -348,12 +377,16 @@ export function statusOf(r: Run, now: number): Status {
   return now - r.moved < RUNNING_WITHIN_MS ? "running" : "stalled";
 }
 
-// A stage this build has never heard of still belongs somewhere visible, and
-// PLANNING is the honest guess: the run has started and has not finished.
-export function columnOf(stage: string) {
+// A stage this build has never heard of still belongs somewhere visible. What the
+// run is waiting on says where it really is (a run awaiting the review approval is
+// in Review whatever its stage word), and PLANNING is the honest guess otherwise:
+// the run has started and has not finished.
+export function columnOf(stage: string, awaiting: string | null = null) {
   if (stage === "build") return 2;
   if (stage === "review") return 3;
   if (stage === "done" || stage === "abandoned") return 4;
+  if (awaiting === "approvals.review" || awaiting === "findings") return 3;
+  if (awaiting === "approvals.each_file") return 2;
   return 1;
 }
 
@@ -588,7 +621,7 @@ export function boardCards(states: string[], now: number): Card[] {
     }
     for (const r of readRuns(st)) {
       next.push({
-        kind: "run", id: r.id, status: statusOf(r, now), text: short(r.id), state: st, where, column: columnOf(r.stage), moved: r.moved,
+        kind: "run", id: r.id, status: statusOf(r, now), text: short(r.id), state: st, where, column: columnOf(r.stage, r.awaiting), moved: r.moved,
         title: requestTitle(body(st, r.id)),
         awaiting: r.stage === "abandoned" ? null : r.awaiting,
         dim: r.stage === "abandoned",
@@ -613,10 +646,11 @@ export function projectOf(from: string) {
     : (from.endsWith(".kaizen") ? dirname(from) : from);
 }
 
-export function manualCommand(projectDir: string, agentCmd: string, prompt: string) {
+export function manualCommand(projectDir: string, agentCmd: string, prompt: string, flags: string[] = []) {
+  const bin = [agentCmd, ...flags].join(" ");
   return process.platform === "win32"
-    ? `cd '${projectDir}'; & ${agentCmd} '${prompt.replace(/'/g, "''")}'`
-    : `cd "${projectDir}" && ${agentCmd} "${prompt}"`;
+    ? `cd '${projectDir}'; & ${bin} '${prompt.replace(/'/g, "''")}'`
+    : `cd "${projectDir}" && ${bin} "${prompt}"`;
 }
 
 export function launchRun(it: Item, from: string): Launch {
@@ -626,8 +660,9 @@ export function launchRun(it: Item, from: string): Launch {
   const agent = detectDefaultAgent(projectDir);
   const agentBin = Bun.which(agent.cmd) ?? agent.cmd;
   const prompt = requestOf(it.where ? `/kaizen ${it.text} (${it.where})` : `/kaizen ${it.text}`, it.notes, from);
-  const fullCmd = [agentBin, prompt];
-  const manual = manualCommand(projectDir, agent.cmd, prompt);
+  const flags = agentFlags(projectDir, agent.cmd);
+  const fullCmd = [agentBin, ...flags, prompt];
+  const manual = manualCommand(projectDir, agent.cmd, prompt, flags);
 
   const term = findTerminal(projectDir, fullCmd);
   if (!term) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.5.5",
+  "version": "1.6.0",
   "description": "Staged workflow for AI agents — code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {

package/skills/kaizen/README.md

@@ -206,7 +206,7 @@ the defaults.
 | `auto_fix.max_iterations` | `2` | Fix/recheck rounds before whatever is left is escalated to you |
 | `review.memory_max_lines` | `100` | The cap on `memory.md`, which every stage of every run reads. Raise only if the lessons are genuinely all load-bearing |
 | `git.auto_commit` | `false` | Leave it. Kaizen does not commit or push unless you ask |
-| `track.default` | `""` (inferred) | A repo that is always one kind of work, e.g. a docs repo |
+| `track.default` | `auto` (inferred) | A repo that is always one kind of work, e.g. a docs repo |
 | `backlog.enabled` | `true` | Set `false` to skip both backlog capture points; the run still executes, just without a `06-backlog.md` |
 | `backlog.file` | `06-backlog.md` | The per-run file name. Rarely. |
 | `backlog.statuses` | `[open, done, rejected]` | Rarely. Only `open` items are printed |

package/skills/kaizen/SKILL.md

@@ -100,6 +100,8 @@ nearest first, so a change lands globally unless this project keeps its own conf
 | `git.auto_commit` | `true`, `false` | Commit the work when a run finishes |
 | `git.branch_before_implement` | `true`, `false` | Branch before building when on the default branch |
 | `ui.mouse` | `false`, `true` | Click to select, click again to act; while on, the terminal cannot select text |
+| `subagents.model` | `inherit`, `opus`, `sonnet`, `haiku` | Model the stage subagents run on (Claude Code only) |
+| `subagents.effort` | `inherit`, `low`, `medium`, `high` | Reasoning effort for the stage subagents (Claude Code only) |
 | `agent.default` | `auto`, `claude`, `codex`, `agy`, `opencode`, `gemini` | Coding agent to launch from dashboard backlog |
 
 Rules for writing the file:
@@ -114,7 +116,8 @@ Rules for writing the file:
 - After writing, print the setting and its new value, and nothing else. No summary of
   the whole file.
 
-Settings not in the table — the review checks, backlog and state paths — are edited by
+Settings not in the table — the review checks, backlog and state paths, and the per-tool
+`agent.<cmd>.model` / `agent.<cmd>.effort` the board launches a session with — are edited by
 hand in `config.yml`, which is commented throughout. Say so rather than offering a
 picker with thirty options.
 
@@ -318,6 +321,13 @@ the choice at the plan approval. Building inline does not make the review less
 independent: the reviewer is a separate agent in every case, and never sees the
 conversation the work happened in.
 
+`subagents.model` and `subagents.effort` apply to every stage dispatched this way.
+Pass `model` on the Agent call when it is not `inherit`. Effort has no call-time
+knob: when it is not `inherit`, make sure the frontmatter of the agent's definition
+(`~/.claude/agents/kaizen-<stage>.md`, or the project's `.claude/agents/` copy)
+carries `effort: <value>` — edit or add that one line, nothing else — before the
+first dispatch of the run. `inherit` means leave the file alone.
+
 After a subagent returns, update `state.json` yourself in the main thread. Subagents
 report; the main thread owns the state machine.
 

package/skills/kaizen/config.default.yml

@@ -64,8 +64,8 @@ track:
   # request by the planner and stated back in the plan's Framing for the user to
   # correct at the approval — the user is never asked to categorize their own request.
   # Set this only to pin a default for a repo that is always one kind of work
-  # (e.g. a docs repo). Leave empty to infer per run.
-  default: ""
+  # (e.g. a docs repo). auto (or empty) infers per run.
+  default: auto
 
 review:
   # Checks that run in every track.
@@ -138,8 +138,30 @@ ui:
   # run id out of the dashboard stops working until you leave.
   mouse: false
 
+subagents:
+  # Claude Code only: other tools (Codex, Antigravity, opencode, gemini) have no
+  # per-stage model knob and run every stage on whatever the tool itself is set to.
+  # Model each stage subagent runs on, when the runner is full.
+  #   inherit - whatever the main session uses. The default.
+  #   opus | sonnet | haiku - pin it. A cheaper model for the builder is the usual
+  #   reason to touch this; the reviewer on a cheaper model finds less.
+  model: inherit
+  # Reasoning effort for the stage subagents: inherit | low | medium | high.
+  # Set through the agent definition's frontmatter.
+  effort: inherit
+
 agent:
   # Default coding agent to launch from dashboard backlog (auto | claude | codex | agy | opencode | gemini).
   # auto picks Claude Code if installed, otherwise the first agent found on PATH.
   default: auto
+  # Per-tool model and effort for the session the board launches, passed as that
+  # tool's own flags (claude --model/--effort, agy --model/--effort, codex -m and
+  # model_reasoning_effort, gemini -m, opencode -m). Model names are the tool's own:
+  # `agy models`, `opencode models`, Claude's opus|sonnet|haiku. Absent = tool default.
+  # Uncomment the tool you launch:
+  # claude: { model: opus, effort: high }
+  # codex: { model: gpt-5, effort: low }
+  # agy: { model: gemini-3.1-pro-low }
+  # opencode: { model: anthropic/claude-sonnet-4-6 }
+  # gemini: { model: gemini-2.5-pro }
 

package/skills/kaizen/spec.md

@@ -104,6 +104,18 @@ Write into `00-request.md`: the verbatim request, the deliverable, what done mea
 and what wrong means. Record in `state.json`: `id`, `mode`, `runner`, `agent`, `track`,
 `stage: "plan"`, `awaiting: null`.
 
+`stage` takes exactly one of five words, and boards key their columns on them:
+`plan`, `build`, `review`, `done`, `abandoned`. Set it when the stage starts —
+`build` before the builder touches anything, `review` before the reviewer reads — as
+its own write, not tacked onto a longer command that may not finish. Any other word
+(`implement`, `fix`, `building`) is unknown to every reader and shows as still planning.
+
+`awaiting` is `null` or the config key of the approval being waited on —
+`approvals.plan`, `approvals.review`, `approvals.each_file` — or `findings` when the
+run has stopped for the user to pick which review findings to fix. Boards read it to
+say what a run is waiting for and where it sits; a word outside this list is shown but
+not understood.
+
 `agent` is the tool this run is happening in — `claude`, `codex`, `agy`, `opencode`,
 `gemini`, or `cursor` — written once at intake and never changed, so a board can say
 which agent to look for when a run is waiting. The tool running this stage knows what

package/skills/kaizen-help/SKILL.md

@@ -85,7 +85,7 @@ Each iteration is written to `runs/<id>/05-iterations/`.
 | `auto_fix.enabled` | `true` | Auto-fix findings vs. escalate everything |
 | `auto_fix.min_severity` | `high` | Threshold for auto-fix (`critical\|high\|medium\|low`) |
 | `auto_fix.max_iterations` | `2` | Fix/recheck rounds before escalating remaining findings |
-| `track.default` | `""` (empty, inferred per run) | Pin a track for a repo that is always one kind of work |
+| `track.default` | `auto` (inferred per run) | Pin a track for a repo that is always one kind of work |
 | `review.write_memory` | `true` | Let the reviewer append lessons to `.kaizen/memory.md` |
 | `backlog.enabled` | `true` | Capture what a run deliberately did not do |
 | `backlog.file` | `06-backlog.md` | Per-run backlog file |
@@ -94,7 +94,10 @@ Each iteration is written to `runs/<id>/05-iterations/`.
 | `state.keep_runs` | `20` | Completed runs kept before pruning oldest (rescues open backlog first) |
 | `git.auto_commit` | `false` | Never commit/push/PR unless the user explicitly asks |
 | `git.branch_before_implement` | `true` | Branch before implement stage when on the default branch |
+| `subagents.model` | `inherit` | Model the stage subagents run on (opus/sonnet/haiku, Claude Code only) |
+| `subagents.effort` | `inherit` | Reasoning effort for the stage subagents (low/medium/high, Claude Code only) |
 | `agent.default` | `auto` | Coding agent to launch from dashboard backlog |
+| `agent.<cmd>.model`, `.effort` | — | Model/effort flags for the launched session, per tool (`claude`, `codex`, `agy`, `opencode`, `gemini`); model names are the tool's own |
 
 `.kaizen/config.yml` overrides only the keys it sets; everything else falls back to
 this skill's `config.default.yml`.

package/web/board.html

@@ -411,7 +411,7 @@ async function openSettings(){
  $("psub").textContent=cfg?`theme is this browser's; the rest is ${cfg.file}`:"theme is this browser's";
  $("pbody").innerHTML=`<div class="set"><label>Theme</label>${opts("th",["system","light","dark"],cur)}
   <label>Notifications</label><div class="opts" id="nt"><button>${typeof Notification==="undefined"?"unsupported":Notification.permission==="granted"?"on":"ask"}</button></div></div>
-  ${cfg?`<hr style="border:0;border-top:1px solid var(--line);margin:16px 0"><div class="set">${cfg.rows.map(r=>`<label title="${esc(r.help)}">${r.key}</label>${opts("s-"+r.key.replace(/\./g,"-"),r.values,r.value)}`).join("")}</div>`:`<p style="color:var(--dim);margin-top:20px">Settings could not be read. Run <code>kaizen settings</code>.</p>`}`;
+  ${cfg?`<hr style="border:0;border-top:1px solid var(--line);margin:16px 0"><div class="set">${cfg.rows.map(r=>`<label title="${esc(r.key+" — "+r.help)}">${r.label}</label>${opts("s-"+r.key.replace(/\./g,"-"),r.values,r.value)}`).join("")}</div>`:`<p style="color:var(--dim);margin-top:20px">Settings could not be read. Run <code>kaizen settings</code>.</p>`}`;
  $("th").querySelectorAll("button").forEach(b=>b.onclick=()=>{const t=b.dataset.v;if(t==="system")delete document.documentElement.dataset.theme;else document.documentElement.dataset.theme=t;try{t==="system"?localStorage.removeItem("kz-theme"):localStorage.setItem("kz-theme",t)}catch(e){}openSettings()});
  $("nt").querySelector("button").onclick=()=>{askNotify();setTimeout(openSettings,300)};
  if(cfg)cfg.rows.forEach(r=>$("s-"+r.key.replace(/\./g,"-")).querySelectorAll("button").forEach(b=>b.onclick=async()=>{if(b.classList.contains("on"))return;const j=await post("/settings",{key:r.key,value:b.dataset.v});if(j.ok)toast(`saved ${r.key} = ${b.dataset.v||'""'}`);openSettings()}))}